@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Assess API
@base https://api.codat.io
@version 1.0
@auth ApiKey Authorization in header
@endpoints 20
@toc data(12), companies(8)

@group data
@endpoint GET /data/companies/{companyId}/assess/dataTypes/{dataType}/dataIntegrity/status
@desc Get data integrity status
@returns(200) {metadata: [map]} # OK
@errors {401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /data/companies/{companyId}/assess/dataTypes/{dataType}/dataIntegrity/summaries
@desc Get data integrity summary
@optional {query: str # Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).}
@returns(200) {summaries: [map]} # OK
@errors {400: Your `query` parameter was not correctly formed, 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /data/companies/{companyId}/assess/dataTypes/{dataType}/dataIntegrity/details
@desc List data type data integrity
@optional {page: int(int32)=1 # Page number. [Read more](https://docs.codat.io/using-the-api/paging)., pageSize: int(int32)=100 # Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging)., query: str # Codat query string. [Read more](https://docs.codat.io/using-the-api/querying)., orderBy: str # Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).}
@returns(200) OK
@errors {400: Your `query` parameter was not correctly formed, 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endgroup

@group companies
@endpoint GET /companies/{companyId}/reports/enhancedProfitAndLoss/accounts
@desc Get enhanced profit and loss accounts
@required {reportDate: str # The date in which the report is created up to. Users must specify a specific date, however the response will be provided for the full month.}
@optional {numberOfPeriods: int # The number of periods to return. If not provided, 12 periods will be used as the default value.}
@returns(200) {reportInfo: map{currency: str(ISO4217), reportName: str, companyName: str, generatedDate: str}, reportItems: [map]} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /companies/{companyId}/reports/enhancedBalanceSheet/accounts
@desc Get enhanced balance sheet accounts
@required {reportDate: str # The date in which the report is created up to. Users must specify a specific date, however the response will be provided for the full month.}
@optional {numberOfPeriods: int # The number of periods to return. If not provided, 12 periods will be used as the default value.}
@returns(200) {reportInfo: map{currency: str(ISO4217), reportName: str, companyName: str, generatedDate: str}, reportItems: [map]} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /companies/{companyId}/reports/enhancedCashFlow/transactions
@desc Get enhanced cash flow report
@optional {page: int(int32)=1 # Page number. [Read more](https://docs.codat.io/using-the-api/paging)., pageSize: int(int32)=100 # Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging)., query: str # Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).}
@returns(200) {reportInfo: map{pageNumber: int, pageSize: int, totalResults: int, reportName: str, companyName: str, generatedDate: str}, dataSources: [map], reportItems: [map]} # OK
@errors {400: Your `query` parameter was not correctly formed, 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /companies/{companyId}/reports/enhancedInvoices
@desc Get enhanced invoices report
@optional {page: int(int32)=1 # Page number. [Read more](https://docs.codat.io/using-the-api/paging)., pageSize: int(int32)=100 # Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging)., query: str # Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).}
@returns(200) {reportInfo: map{pageNumber: int, pageSize: int, totalResults: int, reportName: str, companyName: str, generatedDate: str}, reportItems: [map]} # OK
@errors {400: Your `query` parameter was not correctly formed, 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endgroup

@group data
@endpoint GET /data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/revenue
@desc Get commerce revenue metrics
@required {reportDate: str # The date in which the report is created up to. Users must specify a specific date, however the response will be provided for the full month., periodLength: int # The number of months per period. E.g. 2 = 2 months per period., numberOfPeriods: int # The number of periods to return. There will be no pagination as a query parameter., periodUnit: str(Day/Week/Month/Year) # The period unit of time returned.}
@optional {includeDisplayNames: bool # Shows the dimensionDisplayName and itemDisplayName in measures to make the report data human-readable.}
@returns(200) {reportInfo: map, dimensions: [map], measures: [map], reportData: [map], errors: [map]} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/orders
@desc Get orders report
@required {reportDate: str # The date in which the report is created up to. Users must specify a specific date, however the response will be provided for the full month., periodLength: int # The number of months per period. E.g. 2 = 2 months per period., numberOfPeriods: int # The number of periods to return. There will be no pagination as a query parameter., periodUnit: str(Day/Week/Month/Year) # The period unit of time returned.}
@optional {includeDisplayNames: bool # Shows the dimensionDisplayName and itemDisplayName in measures to make the report data human-readable.}
@returns(200) {reportInfo: map, dimensions: [map], measures: [map], reportData: [map], errors: [map]} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/refunds
@desc Get refunds report
@required {reportDate: str # The date in which the report is created up to. Users must specify a specific date, however the response will be provided for the full month., periodLength: int # The number of months per period. E.g. 2 = 2 months per period., numberOfPeriods: int # The number of periods to return. There will be no pagination as a query parameter., periodUnit: str(Day/Week/Month/Year) # The period unit of time returned.}
@optional {includeDisplayNames: bool # Shows the dimensionDisplayName and itemDisplayName in measures to make the report data human-readable.}
@returns(200) {reportInfo: map, dimensions: [map], measures: [map], reportData: [map], errors: [map]} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/customerRetention
@desc Get customer retention metrics
@required {reportDate: str # The date in which the report is created up to. Users must specify a specific date, however the response will be provided for the full month., periodLength: int # The number of months per period. E.g. 2 = 2 months per period., numberOfPeriods: int # The number of periods to return. There will be no pagination as a query parameter., periodUnit: str(Day/Week/Month/Year) # The period unit of time returned.}
@optional {includeDisplayNames: bool # Shows the dimensionDisplayName and itemDisplayName in measures to make the report data human-readable.}
@returns(200) {reportInfo: map, dimensions: [map], measures: [map], reportData: [map], errors: [map]} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/lifetimeValue
@desc Get lifetime value metric
@required {reportDate: str # The date in which the report is created up to. Users must specify a specific date, however the response will be provided for the full month., periodLength: int # The number of months per period. E.g. 2 = 2 months per period., numberOfPeriods: int # The number of periods to return. There will be no pagination as a query parameter., periodUnit: str(Day/Week/Month/Year) # The period unit of time returned.}
@optional {includeDisplayNames: bool # Shows the dimensionDisplayName and itemDisplayName in measures to make the report data human-readable.}
@returns(200) {reportInfo: map, dimensions: [map], measures: [map], reportData: [map], errors: [map]} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /data/companies/{companyId}/connections/{connectionId}/assess/accountingMetrics/marketing
@desc Get marketing metrics report
@required {reportDate: str # The date in which the report is created up to. Users must specify a specific date, however the response will be provided for the full month., periodLength: int # The number of months per period. E.g. 2 = 2 months per period., numberOfPeriods: int # The number of periods to return. There will be no pagination as a query parameter., periodUnit: str(Day/Week/Month/Year) # The period unit of time returned.}
@optional {includeDisplayNames: bool # Shows the dimensionDisplayName and itemDisplayName in measures to make the report data human-readable., showInputValues: bool # If set to true, then the system includes the input values within the response.}
@returns(200) {reportInfo: map, dimensions: [map], measures: [map], reportData: [map], errors: [map]} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint POST /data/companies/{companyId}/assess/excel
@desc Generate Excel report
@required {reportType: str(assess/audit/enhancedFinancials/enhancedInvoices/enhancedCashFlow) # The type of report you want to generate and download.}
@returns(200) {lastGenerated: str, inProgress: bool, queued: str, success: bool, errorMessage: str, lastInvocationId: str, reportType: str, fileSize: int?} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /data/companies/{companyId}/assess/excel
@desc Get Excel report status
@required {reportType: str(assess/audit/enhancedFinancials/enhancedInvoices/enhancedCashFlow) # The type of report you want to generate and download.}
@returns(200) {lastGenerated: str, inProgress: bool, queued: str, success: bool, errorMessage: str, lastInvocationId: str, reportType: str, fileSize: int?} # OK
@errors {400: Your `query` parameter was not correctly formed, 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /data/companies/{companyId}/assess/excel/download
@desc Download Excel report
@required {reportType: str(assess/audit/enhancedFinancials/enhancedInvoices/enhancedCashFlow) # The type of report you want to generate and download.}
@returns(200) OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endgroup

@group companies
@endpoint POST /companies/{companyId}/reports/liabilities/loans/transactions
@desc Generate loan transactions report
@returns(202) Accepted
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /companies/{companyId}/reports/liabilities/loans/transactions
@desc List loan transactions
@returns(200) {reportInfo: map{pageNumber: int, pageSize: int, totalResults: int, reportName: str, companyName: str, generatedDate: str}, reportItems: [map]} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint POST /companies/{companyId}/reports/liabilities/loans
@desc Generate loan summaries report
@returns(202) Accepted
@errors {401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endpoint GET /companies/{companyId}/reports/liabilities/loans
@desc Get loan summaries
@returns(200) {reportInfo: map{reportName: str, companyName: str, generatedDate: str}, reportItems: [map]} # OK
@errors {401: Your API request was not properly authorized., 402: An account limit has been exceeded. The type of limit is described in the error property:  - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io., 403: You are using an outdated API key or a key not associated with that resource., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again., 500: There is a problem with our server. Please try again later., 503: The Codat API is temporarily offline for maintenance. Please try again later.}

@endgroup

@end