openapi: 3.1.0
info:
title: Bank Feeds Account mapping Excel reports API
version: 3.0.0
contact:
email: support@codat.io
name: Codat
description: 'Bank Feeds solution enables your SMB users to set up bank feeds from accounts in your application to supported accounting software.
A bank feed is a connection between a source bank account in your application and a target bank account in a supported accounting software.
[Explore solution](https://docs.codat.io/bank-feeds-api/overview) | [See OpenAPI spec](https://github.com/codatio/oas)
---
<!-- Start Codat Tags Table -->
## Endpoints
| Endpoints | Description |
| :- |:- |
| Companies | Create and manage your SMB users'' companies. |
| Connections | Create new and manage existing data connections for a company. |
| Source accounts | Provide and manage lists of source bank accounts. |
| Account mapping | Extra functionality for building an account management UI. |
| Company information | Get detailed information about a company from the underlying platform. |
| Transactions | Create new bank account transactions for a company''s connections, and see previous operations. |
<!-- End Codat Tags Table -->'
termsOfService: https://www.codat.io/legals/
servers:
- description: Production
url: https://api.codat.io
security:
- auth_header: []
tags:
- name: Excel reports
description: Download reports in Excel format.
paths:
/data/companies/{companyId}/assess/excel:
parameters:
- $ref: '#/components/parameters/companyId'
post:
summary: Generate Excel report
tags:
- Excel reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ExcelStatus'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
operationId: generate-excel-report
x-speakeasy-name-override: generate
description: 'The *Generate Excel report* endpoint requests the production of a downloadable Excel file for a report type specified in the `reportType` query parameter.
In response, the endpoint returns the [status](https://docs.codat.io/lending-api#/schemas/ExcelStatus) detailing the current state of the report generation request.
### Report types
| reportType | Description |
|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| `audit` | Identifies inaccurate or out-of-date accounts, helping you to make decisions with confidence. || [audit](https://docs.codat.io/lending/excel/audit-report) | Identify inaccurate or out-of-date accounts, helping you to make decisions with confidence. |
| `enhancedCashFlow` | Provides a fully categorized list of bank transactions for a company, allowing lenders to accurately forecast a company''s cash flow. |
| `enhancedFinancials` | Supports decision-making using fully categorized financial statements to allow lenders to automate their underwriting processes. |
| `enhancedInvoices` | Helps verify that payments have been made against historic invoices. Great for invoice finance lenders. |
[Learn more](https://docs.codat.io/lending/features/excel-download-overview#feature-components) about valid Excel report types.
'
parameters:
- $ref: '#/components/parameters/excelReportType'
get:
summary: Get Excel report status
tags:
- Excel reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ExcelStatus'
'400':
$ref: '#/components/responses/Malformed-Query'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
operationId: get-excel-report-generation-status
x-speakeasy-name-override: get-status
description: "\uFEFFThe *Get Excel report status* returns the status of the report mostly recently requested for Excel generation. It does not return the status of any historical report requests. \n\nPoll this endpoint to check the progress of the report once you have requested its generation. This will not affect the generation of the report. \n\nWhen the report generation completes successfully, the `inProgress` property will be marked as `false` and the `success` field will be marked as `true`."
parameters:
- $ref: '#/components/parameters/excelReportType'
/data/companies/{companyId}/assess/excel/download:
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: Download Excel report
tags:
- Excel reports
responses:
'200':
description: OK
content:
application/octet-stream:
schema: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
operationId: download-excel-report
x-speakeasy-name-override: download
description: "\uFEFFThe *Download Excel report* endpoint downloads the latest successfully generated Excel report of a specified report type for a given company. \n\nThe downloadable Excel file is returned in the response. You can save it to your local machine.\n\nYou can [learn more](https://docs.codat.io/lending/features/excel-download-overview#feature-components) about valid Excel report types."
parameters:
- $ref: '#/components/parameters/excelReportType'
components:
responses:
BadRequest:
description: The request made is not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Malformed query:
value:
statusCode: 400
service: PublicApi
error: Error processing request - not valid.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
Payment-Required:
description: '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.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Conflict:
value:
statusCode: 429
service: PublicApi
error: You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
Forbidden:
description: You are using an outdated API key or a key not associated with that resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Conflict:
value:
statusCode: 403
service: PublicApi
error: You are using an outdated API key or a key not associated with that resource.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
Too-Many-Requests:
description: Too many requests were made in a given amount of time. Wait a short period and then try again.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Conflict:
value:
statusCode: 429
service: PublicApi
error: You have made too many requests in a given amount of time; please retry later.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
Unauthorized:
description: Your API request was not properly authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Unauthorized:
value:
statusCode: 401
service: PublicApi
error: Unauthorized
correlationId: 7eb40d6b415d7bcd99ce658268284056
canBeRetried: Unknown
detailedErrorCode: 0
Not-Found:
description: '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.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Data connection not found:
value:
statusCode: 404
service: PublicApi
error: Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found
correlationId: 8fa2b5f4794970a4ee73758f612e8df0
canBeRetried: Unknown
detailedErrorCode: 0
Company not found:
value:
statusCode: 404
service: ClientsApi
error: No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e
correlationId: 0a40c2f31fc8f992fb88b0853e4166f3
canBeRetried: Unknown
detailedErrorCode: 0
No data available:
value:
statusCode: 404
service: PublicApi
error: No data available for accounts for ID e5889b459f544926ac5b8e6756df2s
correlationId: 0a40c2f31fc8f992fb88b0853e4166f3
canBeRetried: Unknown
detailedErrorCode: 0
Malformed-Query:
description: Your `query` parameter was not correctly formed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Malformed query:
value:
statusCode: 400
service: ClientsApi
error: Error parsing query - Malformed query.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
Unresolved property:
value:
statusCode: 400
service: PullApi
error: Error parsing query - Could not resolve property isCompleted on Dataset
correlationId: 98457fb9956b7f9b4b2fd4f6e23bb5c8
canBeRetried: Unknown
detailedErrorCode: 0
Internal-Server-Error:
description: There is a problem with our server. Please try again later.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Conflict:
value:
statusCode: 500
service: PublicApi
error: There is a problem with our server. Please try again later.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
Service-Unavailable:
description: The Codat API is temporarily offline for maintenance. Please try again later.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Conflict:
value:
statusCode: 500
service: PublicApi
error: The Codat API is temporarily offline for maintenance. Please try again later.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
parameters:
companyId:
name: companyId
in: path
required: true
schema:
type: string
format: uuid
example: 8a210b68-6988-11ed-a1eb-0242ac120002
description: Unique identifier for your SMB in Codat.
description: Unique identifier for a company.
excelReportType:
name: reportType
in: query
schema:
$ref: '#/components/schemas/ExcelStatus/definitions/excelReportTypes'
description: The type of report you want to generate and download.
required: true
schemas:
ExcelStatus:
type: object
title: Excel status
properties:
lastGenerated:
$ref: '#/components/schemas/DateTime'
description: The date and time of when the generation of the most recent report was initiated.
inProgress:
type: boolean
description: When true, the request was successful and the report is being generated. If false, the request was unsuccessful and the report is not being generated.
queued:
type: string
description: The date and time of when a successful request was queued for the most recent report.
success:
type: boolean
description: True if the requested report was successfully queued and false if the requested report was not able to be queued.
errorMessage:
type: string
description: Error details in case the report generation request was unsuccessful.
lastInvocationId:
type: string
description: A unique ID generated for this request.
reportType:
$ref: '#/components/schemas/ExcelStatus/definitions/excelReportTypes'
fileSize:
type: integer
nullable: true
description: The file size in Bytes is populated upon successful generation of the report.
definitions:
excelReportTypes:
type: string
enum:
- audit
- enhancedFinancials
- enhancedInvoices
- enhancedCashFlow
description: The type of the report requested in the query string.
examples:
- lastGenerated: '2023-01-25T22:36:05.125Z'
inProgress: true
queued: '2023-01-25T22:36:05.125Z'
success: true
errorMessage: string
lastInvocationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
reportType: string
fileSize: 0
DateTime:
title: Date time
type: string
examples:
- '2022-10-23T00:00:00Z'
- '2022-10-23'
description: "In Codat's data model, dates and times are represented using the <a class=\"external\" href=\"https://en.wikipedia.org/wiki/ISO_8601\" target=\"_blank\">ISO 8601 standard</a>. Date and time fields are formatted as strings; for example:\n\n```\n2020-10-08T22:40:50Z\n2021-01-01T00:00:00\n```\n\n\n\nWhen syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:\n\n- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`\n- Unqualified local time: `2021-11-15T01:00:00`\n- UTC time offsets: `2021-11-15T01:00:00-05:00`\n\n> Time zones\n> \n> Not all dates from Codat will contain information about time zones. \n> Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced."
ErrorMessage:
title: Error message
type: object
x-internal: true
properties:
statusCode:
type: integer
description: The HTTP status code returned by the error.
service:
type: string
description: Codat's service the returned the error.
error:
type: string
description: A brief description of the error.
correlationId:
type: string
description: Unique identifier used to propagate to all downstream services and determine the source of the error.
validation:
$ref: '#/components/schemas/ErrorMessage/definitions/errorValidation'
canBeRetried:
type: string
description: '`True` if the error occurred transiently and can be retried.'
detailedErrorCode:
type: integer
description: Machine readable error code used to automate processes based on the code returned.
definitions:
errorValidation:
title: Validation error
type: object
nullable: true
description: A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.
properties:
errors:
type: array
nullable: true
items:
$ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem'
warnings:
type: array
nullable: true
items:
$ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem'
errorValidationItem:
title: Validation error item
type: object
properties:
itemId:
type: string
nullable: true
description: Unique identifier for a validation item.
message:
type: string
nullable: true
description: A message outlining validation item's issue.
validatorName:
type: string
nullable: true
description: Name of validator.
securitySchemes:
auth_header:
name: Authorization
description: The word "Basic" followed by a space and your API key. [API keys](https://docs.codat.io/platform-api#/schemas/ApiKeyDetails) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/platform-api#/operations/list-api-keys), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.
type: apiKey
in: header
x-speakeasy-example: Basic BASE_64_ENCODED(API_KEY)
x-speakeasy-retries:
strategy: backoff
backoff:
initialInterval: 500
maxInterval: 60000
maxElapsedTime: 3600000
exponent: 1.5
statusCodes:
- 408
- 429
- 5XX
retryConnectionErrors: true
x-speakeasy-name-override:
- operationId: ^list-.*?
methodNameOverride: list
- operationId: ^list-.*?-attachments
methodNameOverride: list-attachments
- operationId: ^get-.*?
methodNameOverride: get
- operationId: ^get-create-.*?-model
methodNameOverride: get-create-model
- operationId: ^get-create-update.*?-model
methodNameOverride: get-create-update-model
- operationId: ^get-.*?-attachment
methodNameOverride: get-attachment
- operationId: ^update-.*?
methodNameOverride: update
- operationId: ^create-.*?
methodNameOverride: create
- operationId: ^delete-.*?
methodNameOverride: delete
- operationId: ^delete-.*?-attachment
methodNameOverride: delete-attachment
- operationId: ^download-.*?-attachment
methodNameOverride: download-attachment
- operationId: ^upload-.*?-attachment
methodNameOverride: upload-attachment
x-codat-docs-path: bank-feeds-api
x-codat-keep-docs-paths-local: true
x-codat-speakeasy-pagination:
type: offsetLimit
inputs:
- name: page
in: parameters
type: page
outputs:
results: $.results