openapi: 3.1.0
servers:
- description: Production
url: 'https://api.codat.io'
info:
title: Bank Feeds API
version: 3.0.0
contact:
email: support@codat.io
name: Codat
description: |-
Bank Feeds API 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 product](https://docs.codat.io/bank-feeds-api/overview) | [See OpenAPI spec](https://github.com/codatio/oas)
---
## 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. |
termsOfService: 'https://www.codat.io/legals/'
security:
- auth_header: []
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
tags:
- name: Companies
description: Create and manage your SMB users' companies.
- name: Connections
description: Create new and manage existing data connections for a company.
- name: Configuration
description: Configure bank feeds for a company.
- name: Bank accounts
description: Access bank accounts in an SMBs accounting software.
- name: Source accounts
description: Provide and manage lists of source bank accounts.
- name: Sync
description: Monitor the status of data syncs.
- name: Account mapping
description: Extra functionality for building an account management UI.
- name: Transactions
description: 'Create new bank account transactions for a company''s connections, and see previous operations.'
- name: Company information
description: Get detailed information about a company from the underlying accounting software.
paths:
/companies:
post:
summary: Create company
tags:
- Companies
operationId: create-company
responses:
'200':
description: OK
content:
application/json:
x-speakeasy-usage-example: true
schema:
$ref: '#/components/schemas/Company'
examples:
With no description:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: Technicalium
description: ''
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18.1950523Z'
createdByUserName: Dan Tzabar
With a description:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: Technicalium
description: 'Technology services, including web and app design and development'
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18.1950523Z'
createdByUserName: Dan Tzabar
With a tag:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: Technicalium
description: ''
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18.1950523Z'
createdByUserName: Dan Tzabar
tags:
region: us
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
description: "\uFEFFUse the *Create company* endpoint to create a new [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) that represents your customer in Codat. \n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n\nIf forbidden characters (see `name` pattern) are present in the request, a company will be created with the forbidden characters removed. For example, `Company (Codat[1])` with be created as `Company Codat1`."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyRequestBody'
examples:
With no description:
value:
name: Technicalium
With a description:
value:
name: Technicalium
description: 'Technology services, including web and app design and development'
get:
summary: List companies
tags:
- Companies
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Companies'
examples:
One company:
value:
results:
- id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
name: My Test Company
description: My Test Company make testing software
platform: ''
redirect: 'https://link.codat.io/company/3fa85f64-5717-4562-b3fc-2c963f66afa6'
lastSync: '2022-01-01T12:30:00.000Z'
dataConnections:
- id: 51baa045-4836-4317-a42e-3542e991e581
integrationId: 1c312d69-e638-46d4-ad31-72e6c3ba8390
integrationKey: vjms
sourceId: 396c3158-5dd7-481b-a7c4-a795ca31792b
platformName: Pandle
linkUrl: 'https://link-api.codat.io/companies/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections/51baa045-4836-4317-a42e-3542e991e581/start'
status: Linked
lastSync: '2022-01-01T12:30:00.000Z'
created: '2022-01-01T11:30:00Z'
sourceType: Accounting
created: '2022-01-01T11:30:00Z'
createdByUserName: Mike Smith
pageNumber: 1
pageSize: 100
totalResults: 1
_links:
current:
href: /companies?page=1&pageSize=100
self:
href: /companies
List of Companies:
value:
results:
- id: d1568dde-adf6-11ed-afa1-0242ac120002
name: Technicalium
description: 'Technology services, including web and app design and development'
platform: ''
redirect: 'https://link.codat.io/company/d1568dde-adf6-11ed-afa1-0242ac120002'
lastSync: '2022-01-01T12:30:00.000Z'
dataConnections:
- id: 51baa045-4836-4317-a42e-3542e991e581
integrationId: 1c312d69-e638-46d4-ad31-72e6c3ba8390
integrationKey: vjms
sourceId: 396c3158-5dd7-481b-a7c4-a795ca31792b
platformName: Pandle
linkUrl: 'https://link-api.codat.io/companies/d1568dde-adf6-11ed-afa1-0242ac120002/connections/51baa045-4836-4317-a42e-3542e991e581/start'
status: Linked
lastSync: '2022-01-01T12:30:00.000Z'
created: '2022-01-01T11:30:00Z'
sourceType: Accounting
created: '2022-01-01T11:30:00Z'
createdByUserName: Joe Bloggs
- id: 096db70b-78de-4ff0-aa98-299cb5fe17a0
name: Godata
description: A new digital agency with a passion for creating amazing digital experiences
platform: ''
redirect: 'https://link.codat.io/company/096db70b-78de-4ff0-aa98-299cb5fe17a0'
lastSync: '2022-01-01T12:30:00.000Z'
dataConnections:
- id: a70bc148-dc21-46b2-a257-d9c58ac15cbb
integrationId: 1c312d69-e638-46d4-ad31-72e6c3ba8390
integrationKey: vjms
sourceId: 396c3158-5dd7-481b-a7c4-a795ca31792b
platformName: Pandle
linkUrl: 'https://link-api.codat.io/companies/096db70b-78de-4ff0-aa98-299cb5fe17a0/connections/a70bc148-dc21-46b2-a257-d9c58ac15cbb/start'
status: Linked
lastSync: '2022-01-01T12:30:00.000Z'
created: '2022-01-01T11:30:00Z'
sourceType: Accounting
created: '2022-01-01T11:30:00Z'
createdByUserName: Mike Smith
pageNumber: 1
pageSize: 100
totalResults: 2
_links:
current:
href: /companies?page=1&pageSize=100
self:
href: /companies
'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: list-companies
description: "\uFEFFThe *List companies* endpoint returns a list of [companies] associated to your instances.\n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data."
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
'/companies/{companyId}':
get:
summary: Get company
operationId: get-company
description: "\uFEFFThe *Get company* endpoint returns a single company for a given `companyId`.\n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n"
parameters:
- $ref: '#/components/parameters/companyId'
tags:
- Companies
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
examples:
Simple company:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: My First Company
description: ''
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18Z'
createdByUserName: Dan Tzabar
'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'
delete:
summary: Delete a company
operationId: delete-company
parameters:
- $ref: '#/components/parameters/companyId'
description: "\uFEFFThe *Delete company* endpoint permanently deletes a [company](https://docs.codat.io/bank-feeds-api#/schemas/Company), its [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) and any cached data. This operation is irreversible.\n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n"
tags:
- Companies
responses:
'204':
description: No Content
'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'
put:
summary: Update company
description: "\uFEFFUse the *Update company* endpoint to update both the name and description of the company. \n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data."
operationId: update-company
parameters:
- $ref: '#/components/parameters/companyId'
tags:
- Companies
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
'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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyRequestBody'
examples:
Update name:
value:
name: New Name
Update description:
value:
name: Same name
description: Additional documents required
'/companies/{companyId}/connections':
get:
summary: List connections
description: "\uFEFFList the connections for a company."
operationId: list-connections
tags:
- Connections
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Connections'
examples:
Connections:
value:
results:
- id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd
integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c
integrationKey: dfxm
sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee
platformName: Basiq
linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: '2022-10-27T10:22:43.6464237Z'
created: '2022-10-27T09:53:29Z'
sourceType: Banking
pageNumber: 0
pageSize: 0
totalResults: 0
_links:
self:
href: string
current:
href: string
next:
href: string
previous:
href: string
'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'
post:
summary: Create connection
description: "\uFEFFCreates a connection for the company by providing a valid `platformKey`. \n\nUse the [List Integrations](https://docs.codat.io/bank-feeds-api#/operations/list-integrations) endpoint to access valid platform keys. "
parameters:
- $ref: '#/components/parameters/companyId'
tags:
- Connections
operationId: create-connection
requestBody:
content:
application/json:
schema:
type: object
properties:
platformKey:
type: string
minLength: 4
maxLength: 4
pattern: '[a-z]{4}'
example: gbol
description: 'A unique 4-letter key to represent a platform in each integration. View [accounting](https://docs.codat.io/integrations/accounting/overview#platform-keys), [banking](https://docs.codat.io/integrations/banking/overview#platform-keys), and [commerce](https://docs.codat.io/integrations/commerce/overview#platform-keys) platform keys.'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
examples:
Connection:
value:
id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd
integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c
integrationKey: dfxm
sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee
platformName: Basiq
linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: '2022-10-27T10:22:43.6464237Z'
created: '2022-10-27T09:53:29Z'
sourceType: Banking
'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'
'/companies/{companyId}/connections/{connectionId}':
get:
summary: Get connection
operationId: get-connection
description: "\uFEFFReturns a specific connection for a company when valid identifiers are provided. If the identifiers are for a deleted company and/or connection, a not found response is returned."
tags:
- Connections
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
examples:
Connection:
value:
id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd
integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c
integrationKey: dfxm
sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee
platformName: Basiq
linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: '2022-10-27T10:22:43.6464237Z'
created: '2022-10-27T09:53:29Z'
sourceType: Banking
'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'
delete:
summary: Delete connection
operationId: delete-connection
description: "\uFEFFRevoke and remove a connection from a company.\nThis operation is not reversible. The end user would need to reauthorize a new data connection if you wish to view new data for this company."
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
tags:
- Connections
responses:
'200':
description: OK
'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'
patch:
summary: Unlink connection
description: "\uFEFFThis allows you to deauthorize a connection, without deleting it from Codat. This means you can still view any data that has previously been pulled into Codat, and also lets you re-authorize in future if your customer wishes to resume sharing their data."
operationId: unlink-connection
x-speakeasy-name-override: unlink
tags:
- Connections
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
'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'
requestBody:
content:
application/json:
schema:
title: Update connection
x-internal: true
type: object
properties:
status:
$ref: '#/components/schemas/Connection/definitions/dataConnectionStatus'
description: The current authorization status of the data connection.
nullable: true
additionalProperties: false
examples:
Example:
value:
status: Unlinked
description: ''
'/companies/{companyId}/sync/banking/config':
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: Get configuration
operationId: get-configuration
x-internal: true
tags:
- Configuration
description: "\uFEFFThe *Get configuration* endpoint returns the current configuration for a given company ID."
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Configuration'
examples: {}
'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'
post:
summary: Set configuration
operationId: set-configuration
x-speakeasy-name-override: set
x-internal: true
tags:
- Configuration
description: "\uFEFFUse *Set configuration* endpoint to configure a given company ID."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Configuration'
examples: {}
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Configuration'
examples: {}
'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'
'/companies/{companyId}/sync/banking/syncs/lastSuccessful/status':
get:
tags:
- Sync
description: 'Use the _Get last successful sync_ endpoint to obtain the status information for the company''s [most recent successful sync](https://docs.codat.io/bank-feeds-api#/schemas/CompanySyncStatus). '
parameters:
- $ref: '#/components/parameters/companyId'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CompanySyncStatus'
examples: {}
'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'
summary: Get last successful sync
operationId: get-last-successful
x-speakeasy-name-override: get-last-successful-sync
x-internal: true
'/companies/{companyId}/connections/{connectionId}/data/bankAccounts':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
x-internal: true
tags:
- Bank accounts
summary: List bank accounts
operationId: list-bank-accounts
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccounts'
examples:
Dynamics 365 Business Central:
value:
results:
- id: c9a41bc7-6e5b-ed11-8c34-0022481b8b5b
accountName: '55'
accountType: Unknown
nominalCode: '10500'
sortCode: ''
accountNumber: ''
iBan: ''
currency: GBP
balance: -352.03
modifiedDate: '2023-03-27T14:21:10Z'
sourceModifiedDate: '2023-02-07T00:00:00'
overdraftLimit: 0
metadata:
isDeleted: false
- id: 47020f80-60e6-ec11-82f8-0022481a77f0
accountName: '555'
accountType: Unknown
nominalCode: '40300'
sortCode: ''
accountNumber: ''
iBan: ''
currency: PLN
balance: 661.79
modifiedDate: '2023-03-27T14:21:10Z'
sourceModifiedDate: '2022-06-07T00:00:00'
overdraftLimit: 0
metadata:
isDeleted: false
pageNumber: 1
pageSize: 2
totalResults: 28
_links:
current:
href: /companies/d6849caf-c146-41be-8335-b73346e3bd84/connections/60acb117-5cf5-4745-b069-491551da4066/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/d6849caf-c146-41be-8335-b73346e3bd84/connections/60acb117-5cf5-4745-b069-491551da4066/data/bankAccounts
next:
href: /companies/d6849caf-c146-41be-8335-b73346e3bd84/connections/60acb117-5cf5-4745-b069-491551da4066/data/bankAccounts?page=2&pageSize=2
FreeAgent:
value:
results:
- id: '738783'
accountName: \w3fw
accountType: Debit
sortCode: '236972'
accountNumber: A06268209
currency: GBP
balance: -10484.65
availableBalance: -10484.65
modifiedDate: '2023-04-25T14:19:12Z'
metadata:
isDeleted: false
- id: '738778'
accountName: 2e2bna45hy\
accountType: Debit
sortCode: '236972'
accountNumber: D01825250
currency: GBP
balance: -114.4
availableBalance: -114.4
modifiedDate: '2023-04-25T14:19:12Z'
metadata:
isDeleted: false
pageNumber: 1
pageSize: 2
totalResults: 82
_links:
current:
href: /companies/071ad738-68f3-4561-afd0-69bab9df0803/connections/4fd7c69f-ecc1-45f5-83f2-42ed3391e386/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/071ad738-68f3-4561-afd0-69bab9df0803/connections/4fd7c69f-ecc1-45f5-83f2-42ed3391e386/data/bankAccounts
next:
href: /companies/071ad738-68f3-4561-afd0-69bab9df0803/connections/4fd7c69f-ecc1-45f5-83f2-42ed3391e386/data/bankAccounts?page=2&pageSize=2
KashFlow:
value:
results:
- id: '765768'
accountName: 16th Account
accountType: Unknown
nominalCode: '70700'
currency: GBP
balance: 326
availableBalance: 326
modifiedDate: '2022-09-30T10:29:16Z'
- id: '765766'
accountName: 1a1a
accountType: Unknown
nominalCode: '70600'
currency: GBP
balance: 0
availableBalance: 0
modifiedDate: '2022-09-30T10:29:16Z'
pageNumber: 1
pageSize: 2
totalResults: 56
_links:
current:
href: /companies/3a707a99-89da-4b16-a5d6-595333a16352/connections/ecab4f64-1a04-4c53-a343-bfd879f41f67/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/3a707a99-89da-4b16-a5d6-595333a16352/connections/ecab4f64-1a04-4c53-a343-bfd879f41f67/data/bankAccounts
next:
href: /companies/3a707a99-89da-4b16-a5d6-595333a16352/connections/ecab4f64-1a04-4c53-a343-bfd879f41f67/data/bankAccounts?page=2&pageSize=2
Oracle NetSuite:
value:
results:
- id: '825'
accountName: Codat Europe Bank
accountType: Debit
nominalCode: '111111122222111'
currency: GBP
balance: 558.22
modifiedDate: '2023-05-02T13:24:36Z'
sourceModifiedDate: '2022-07-15T11:34:02'
metadata:
isDeleted: false
- id: '826'
accountName: Codat Europe Bank USD
accountType: Debit
nominalCode: '1133221133'
currency: USD
modifiedDate: '2023-05-02T13:24:36Z'
sourceModifiedDate: '2021-03-26T10:31:40'
metadata:
isDeleted: false
pageNumber: 1
pageSize: 2
totalResults: 4
_links:
current:
href: /companies/d5074b08-6a34-4b06-a742-236edf5dc4f1/connections/79f8313e-210a-4dc8-b69f-ba7e5004dda7/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/d5074b08-6a34-4b06-a742-236edf5dc4f1/connections/79f8313e-210a-4dc8-b69f-ba7e5004dda7/data/bankAccounts
next:
href: /companies/d5074b08-6a34-4b06-a742-236edf5dc4f1/connections/79f8313e-210a-4dc8-b69f-ba7e5004dda7/data/bankAccounts?page=2&pageSize=2
QuickBooks Desktop:
value:
results:
- id: 20000-933270541
accountName: Checking
accountType: Unknown
nominalCode: '10100'
currency: GBP
balance: 46954.1
availableBalance: 46954.1
modifiedDate: '2023-04-26T09:12:37Z'
sourceModifiedDate: '2023-12-16T05:06:45'
metadata:
isDeleted: false
- id: 550001-1071509830
accountName: Petty Cash
accountType: Unknown
nominalCode: '10400'
currency: GBP
balance: 500
availableBalance: 500
modifiedDate: '2023-04-26T09:12:37Z'
sourceModifiedDate: '2023-12-16T05:06:45'
metadata:
isDeleted: false
pageNumber: 1
pageSize: 2
totalResults: 3
_links:
current:
href: /companies/fc72ba08-af13-4474-b28a-01dcfa6cfb51/connections/2c26b4da-97d4-4ba9-baad-1e18b49b96ac/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/fc72ba08-af13-4474-b28a-01dcfa6cfb51/connections/2c26b4da-97d4-4ba9-baad-1e18b49b96ac/data/bankAccounts
next:
href: /companies/fc72ba08-af13-4474-b28a-01dcfa6cfb51/connections/2c26b4da-97d4-4ba9-baad-1e18b49b96ac/data/bankAccounts?page=2&pageSize=2
QuickBooks Online Sandbox:
value:
results:
- id: '164'
accountName: '00'
accountType: Debit
nominalCode: '123567'
currency: GBP
balance: 0
availableBalance: 0
modifiedDate: '2023-04-26T09:35:57Z'
sourceModifiedDate: '2022-07-20T14:11:28Z'
metadata:
isDeleted: false
- id: '163'
accountName: '11'
accountType: Debit
currency: GBP
balance: 0
availableBalance: 0
modifiedDate: '2023-04-26T09:35:57Z'
sourceModifiedDate: '2022-07-20T14:11:28Z'
metadata:
isDeleted: false
pageNumber: 1
pageSize: 2
totalResults: 57
_links:
current:
href: /companies/5a7f3597-36e1-4216-86fe-289ad36088a6/connections/1f9f6013-f8a5-4278-8a47-3ab7fdb6c24c/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/5a7f3597-36e1-4216-86fe-289ad36088a6/connections/1f9f6013-f8a5-4278-8a47-3ab7fdb6c24c/data/bankAccounts
next:
href: /companies/5a7f3597-36e1-4216-86fe-289ad36088a6/connections/1f9f6013-f8a5-4278-8a47-3ab7fdb6c24c/data/bankAccounts?page=2&pageSize=2
QuickBooks Online:
value:
results:
- id: '202'
accountName: \aa
accountType: Debit
currency: GBP
balance: 123
availableBalance: 123
modifiedDate: '2023-01-18T11:02:37Z'
sourceModifiedDate: '2022-11-11T14:15:13Z'
- id: '193'
accountName: 1 year ago
accountType: Debit
currency: GBP
balance: 5300.02
availableBalance: 5300.02
modifiedDate: '2023-01-18T11:02:37Z'
sourceModifiedDate: '2023-01-18T06:05:12Z'
pageNumber: 1
pageSize: 2
totalResults: 140
_links:
current:
href: /companies/10818b5e-6e6a-4ed4-a1c5-3e3efe626e87/connections/9e28a776-f4be-425b-8a3d-ad49956de2c9/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/10818b5e-6e6a-4ed4-a1c5-3e3efe626e87/connections/9e28a776-f4be-425b-8a3d-ad49956de2c9/data/bankAccounts
next:
href: /companies/10818b5e-6e6a-4ed4-a1c5-3e3efe626e87/connections/9e28a776-f4be-425b-8a3d-ad49956de2c9/data/bankAccounts?page=2&pageSize=2
Sage 50 (UK):
value:
results:
- id: '1200'
accountName: Bank Current Account
accountType: Unknown
nominalCode: '1200'
sortCode: 23-34-34
accountNumber: '003234234'
iBan: ''
currency: GBP
balance: -20091.04
availableBalance: -20091.04
modifiedDate: '2023-03-30T14:42:37Z'
sourceModifiedDate: '2022-11-25T09:25:48'
overdraftLimit: 120000
institution: Lloyds Bank PLC
metadata:
isDeleted: false
- id: '1210'
accountName: Bank Deposit Account
accountType: Unknown
nominalCode: '1210'
sortCode: 45-45-45
accountNumber: 9/00474345
iBan: ''
currency: GBP
balance: 3510
availableBalance: 3510
modifiedDate: '2023-03-30T14:42:37Z'
sourceModifiedDate: '2022-11-25T09:25:48'
overdraftLimit: 0
institution: Halifax Building Society
metadata:
isDeleted: false
pageNumber: 1
pageSize: 2
totalResults: 6
_links:
current:
href: /companies/cf5f2a47-2990-4221-bae6-0c19c86ac304/connections/8ee4910f-4fc1-47e6-89b1-5931fb33d8f7/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/cf5f2a47-2990-4221-bae6-0c19c86ac304/connections/8ee4910f-4fc1-47e6-89b1-5931fb33d8f7/data/bankAccounts
next:
href: /companies/cf5f2a47-2990-4221-bae6-0c19c86ac304/connections/8ee4910f-4fc1-47e6-89b1-5931fb33d8f7/data/bankAccounts?page=2&pageSize=2
Sage Business Cloud Accounting:
value:
results:
- id: 154d05abe9f24c4babe0f6a741dec1b9
accountName: Abdi Internet Bank
accountType: Unknown
nominalCode: '1560'
sortCode: '010101'
accountNumber: '11111'
currency: GBP
balance: 49.61
availableBalance: 49.61
modifiedDate: '2022-10-24T14:52:53Z'
sourceModifiedDate: '2020-01-27T10:53:26Z'
- id: 565ce07212bc492c8c2d04f43f9f67e3
accountName: Abdi Live Test
accountType: Unknown
nominalCode: '147852'
sortCode: '123456'
accountNumber: '1234567'
currency: GBP
balance: -225830.75
availableBalance: -225830.75
modifiedDate: '2022-10-24T14:52:53Z'
sourceModifiedDate: '2020-01-28T14:00:20Z'
pageNumber: 1
pageSize: 2
totalResults: 45
_links:
current:
href: /companies/390083e2-351b-407c-a3be-55081c36c182/connections/37916fb7-b4b8-4a78-8872-1751e20ee0cd/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/390083e2-351b-407c-a3be-55081c36c182/connections/37916fb7-b4b8-4a78-8872-1751e20ee0cd/data/bankAccounts
next:
href: /companies/390083e2-351b-407c-a3be-55081c36c182/connections/37916fb7-b4b8-4a78-8872-1751e20ee0cd/data/bankAccounts?page=2&pageSize=2
Sage Intacct:
value:
results:
- id: 'CREDITCARD:55'
accountName: CoT Credit Card
accountType: Credit
nominalCode: '10021'
currency: GBP
modifiedDate: '2023-04-04T16:31:46Z'
sourceModifiedDate: '2023-03-27T14:11:48'
metadata:
isDeleted: false
- id: 'CREDITCARD:58'
accountName: Cot Credit Card 2
accountType: Credit
nominalCode: '11112'
currency: GBP
modifiedDate: '2023-04-04T16:31:46Z'
sourceModifiedDate: '2023-03-27T14:15:11'
metadata:
isDeleted: false
pageNumber: 1
pageSize: 2
totalResults: 14
_links:
current:
href: /companies/df02b289-cb16-4964-ac4d-9fd60b04538e/connections/8f457d9c-1142-4241-a07e-71d1ee2e3052/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/df02b289-cb16-4964-ac4d-9fd60b04538e/connections/8f457d9c-1142-4241-a07e-71d1ee2e3052/data/bankAccounts
next:
href: /companies/df02b289-cb16-4964-ac4d-9fd60b04538e/connections/8f457d9c-1142-4241-a07e-71d1ee2e3052/data/bankAccounts?page=2&pageSize=2
Xero:
value:
results:
- id: bd9e85e0-0478-433d-ae9f-0b3c4f04bfe4
accountName: Business Bank Account
accountType: Debit
sortCode: '990404'
accountNumber: '987654321'
currency: GBP
balance: 6681.79
modifiedDate: '2023-03-15T20:36:09Z'
sourceModifiedDate: '2023-03-15T20:35:07'
metadata:
isDeleted: false
- id: a8d6fb1a-8c5d-4683-90ce-bf9d28fc62ba
accountName: Business Savings Account
accountType: Debit
sortCode: '890303'
accountNumber: '876543210'
currency: GBP
balance: 0
modifiedDate: '2023-03-15T20:36:09Z'
sourceModifiedDate: '2023-03-15T20:36:06'
metadata:
isDeleted: false
pageNumber: 1
pageSize: 2
totalResults: 2
_links:
current:
href: /companies/5ced9667-a310-443a-a711-958d36377141/connections/6a4bcf97-e46a-465c-abf6-c42cec8e48c0/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/5ced9667-a310-443a-a711-958d36377141/connections/6a4bcf97-e46a-465c-abf6-c42cec8e48c0/data/bankAccounts
Zoho Books:
value:
results:
- id: '104957000000060010'
accountName: Abdi Test
accountType: Unknown
sortCode: '112233'
accountNumber: xxxx5678
currency: GBP
balance: 69858.44
modifiedDate: '2022-10-03T08:40:38Z'
institution: Test Bank
- id: '104957000000065002'
accountName: Abdi Test 2
accountType: Unknown
sortCode: ''
accountNumber: ''
currency: AED
balance: 98.03
modifiedDate: '2022-10-03T08:40:38Z'
institution: ''
pageNumber: 1
pageSize: 2
totalResults: 4
_links:
current:
href: /companies/d0b68840-db50-4bc3-b88c-96e225333fea/connections/a2324b8e-60e9-451d-8eb1-0fdc8e8224df/data/bankAccounts?page=1&pageSize=2
self:
href: /companies/d0b68840-db50-4bc3-b88c-96e225333fea/connections/a2324b8e-60e9-451d-8eb1-0fdc8e8224df/data/bankAccounts
next:
href: /companies/d0b68840-db50-4bc3-b88c-96e225333fea/connections/a2324b8e-60e9-451d-8eb1-0fdc8e8224df/data/bankAccounts?page=2&pageSize=2
'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'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
description: |-
The *List bank accounts* endpoint returns a list of [bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) for a given company's connection.
[Bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution.
Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/bank-feeds-api#/operations/refresh-company-data).
'/companies/{companyId}/connections/{connectionId}/options/bankAccounts':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get create/update bank account model
x-internal: true
tags:
- Bank accounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PushOption'
examples:
Dynamics 365 Business Central:
value:
type: Object
displayName: Bank Account
description: An account that bank transactions may be recorded against
properties:
accountName:
type: String
displayName: Name
description: The name of the bank account in the originating system
required: true
validation:
warnings: []
information:
- field: AccountName
details: 'Needs to be of the format ''{No.}-{Name}'''
currency:
type: String
displayName: Currency
description: The currency of the bank account
required: true
accountNumber:
type: String
displayName: Account Number
description: The account number for the bank account
required: false
nominalCode:
type: String
displayName: Nominal Code
description: The external reference given to each nominal account for a business
required: false
validation:
warnings: []
information:
- field: NominalCode
details: Bank Account Posting Group with Nominal Account must exist
sortCode:
type: String
displayName: Sort Code
description: The sort code for the bank account
required: false
validation:
warnings: []
information:
- field: SortCode
details: Must have a length between 0 and 20 characters
iBan:
type: String
displayName: IBAN
description: The international bank account number of the account. Often used when making or receiving international payments
required: false
overdraftLimit:
type: Number
displayName: Overdraft Limit
description: The pre-arranged overdraft limit of the account
required: false
validation:
warnings: []
information:
- field: OverdraftLimit
details: Default value is 0
required: true
Exact (Netherlands):
value:
type: Object
displayName: Bank Account
description: An account that bank transactions may be recorded against
properties:
accountName:
type: String
displayName: Name
description: The name of the bank account in the originating system
required: true
accountNumber:
type: String
displayName: Account Number
description: The account number for the bank account
required: true
validation:
warnings:
- field: AccountNumber
details: Should not exceed the maximum length of 14 characters if the specified currency is GBP.
information: []
sortCode:
type: String
displayName: Sort Code
description: The sort code for the bank account
required: false
validation:
warnings:
- field: SortCode
details: Must be 6 characters long if the specified currency is GBP.
- field: SortCode
details: Must be provided if the specified currency is GBP.
information: []
currency:
type: String
displayName: Currency
description: The currency of the bank account
required: false
nominalCode:
type: String
displayName: Nominal Code
description: The external reference given to each nominal account for a business
required: false
required: true
Exact (UK):
value:
type: Object
displayName: Bank Account
description: An account that bank transactions may be recorded against
properties:
accountName:
type: String
displayName: Name
description: The name of the bank account in the originating system
required: true
accountNumber:
type: String
displayName: Account Number
description: The account number for the bank account
required: true
validation:
warnings:
- field: AccountNumber
details: Should not exceed the maximum length of 14 characters if the specified currency is GBP.
information: []
sortCode:
type: String
displayName: Sort Code
description: The sort code for the bank account
required: false
validation:
warnings:
- field: SortCode
details: Must be 6 characters long if the specified currency is GBP.
- field: SortCode
details: Must be provided if the specified currency is GBP.
information: []
currency:
type: String
displayName: Currency
description: The currency of the bank account
required: false
nominalCode:
type: String
displayName: Nominal Code
description: The external reference given to each nominal account for a business
required: false
required: true
FreeAgent:
value:
type: Object
displayName: Bank Account
description: An account that bank transactions may be recorded against
properties:
accountName:
type: String
displayName: Name
description: The name of the bank account in the originating system
required: true
sortCode:
type: String
displayName: Sort Code
description: The sort code for the bank account
required: false
validation:
warnings:
- field: SortCode
details: Must have a length between 0 and 8 characters
information: []
accountNumber:
type: String
displayName: Account Number
description: The account number for the bank account
required: false
iBan:
type: String
displayName: IBAN
description: The international bank account number of the account. Often used when making or receiving international payments
required: false
currency:
type: String
displayName: Currency
description: The currency of the bank account
options:
- value: AED
type: String
displayName: AED
required: false
- value: AMD
type: String
displayName: AMD
required: false
- value: AOA
type: String
displayName: AOA
required: false
- value: ARS
type: String
displayName: ARS
required: false
- value: AUD
type: String
displayName: AUD
required: false
- value: AWG
type: String
displayName: AWG
required: false
- value: AZN
type: String
displayName: AZN
required: false
- value: BBD
type: String
displayName: BBD
required: false
- value: BDT
type: String
displayName: BDT
required: false
- value: BGN
type: String
displayName: BGN
required: false
- value: BRL
type: String
displayName: BRL
required: false
- value: BWP
type: String
displayName: BWP
required: false
- value: CAD
type: String
displayName: CAD
required: false
- value: CHF
type: String
displayName: CHF
required: false
- value: CLP
type: String
displayName: CLP
required: false
- value: CNY
type: String
displayName: CNY
required: false
- value: COP
type: String
displayName: COP
required: false
- value: CRC
type: String
displayName: CRC
required: false
- value: CUC
type: String
displayName: CUC
required: false
- value: CUP
type: String
displayName: CUP
required: false
- value: CZK
type: String
displayName: CZK
required: false
- value: DKK
type: String
displayName: DKK
required: false
- value: DOP
type: String
displayName: DOP
required: false
- value: EGP
type: String
displayName: EGP
required: false
- value: EUR
type: String
displayName: EUR
required: false
- value: FJD
type: String
displayName: FJD
required: false
- value: GBP
type: String
displayName: GBP
required: false
- value: GEL
type: String
displayName: GEL
required: false
- value: GHS
type: String
displayName: GHS
required: false
- value: GTQ
type: String
displayName: GTQ
required: false
- value: GYD
type: String
displayName: GYD
required: false
- value: HKD
type: String
displayName: HKD
required: false
- value: HNL
type: String
displayName: HNL
required: false
- value: HRK
type: String
displayName: HRK
required: false
- value: HUF
type: String
displayName: HUF
required: false
- value: IDR
type: String
displayName: IDR
required: false
- value: ILS
type: String
displayName: ILS
required: false
- value: INR
type: String
displayName: INR
required: false
- value: ISK
type: String
displayName: ISK
required: false
- value: JMD
type: String
displayName: JMD
required: false
- value: JPY
type: String
displayName: JPY
required: false
- value: KES
type: String
displayName: KES
required: false
- value: KRW
type: String
displayName: KRW
required: false
- value: KWD
type: String
displayName: KWD
required: false
- value: KYD
type: String
displayName: KYD
required: false
- value: KZT
type: String
displayName: KZT
required: false
- value: LAK
type: String
displayName: LAK
required: false
- value: LBP
type: String
displayName: LBP
required: false
- value: LKR
type: String
displayName: LKR
required: false
- value: LTL
type: String
displayName: LTL
required: false
- value: LVL
type: String
displayName: LVL
required: false
- value: MAD
type: String
displayName: MAD
required: false
- value: MDL
type: String
displayName: MDL
required: false
- value: MGA
type: String
displayName: MGA
required: false
- value: MUR
type: String
displayName: MUR
required: false
- value: MVR
type: String
displayName: MVR
required: false
- value: MWK
type: String
displayName: MWK
required: false
- value: MXN
type: String
displayName: MXN
required: false
- value: MYR
type: String
displayName: MYR
required: false
- value: MZN
type: String
displayName: MZN
required: false
- value: NAD
type: String
displayName: NAD
required: false
- value: NGN
type: String
displayName: NGN
required: false
- value: NOK
type: String
displayName: NOK
required: false
- value: NPR
type: String
displayName: NPR
required: false
- value: NZD
type: String
displayName: NZD
required: false
- value: OMR
type: String
displayName: OMR
required: false
- value: PEN
type: String
displayName: PEN
required: false
- value: PHP
type: String
displayName: PHP
required: false
- value: PKR
type: String
displayName: PKR
required: false
- value: PLN
type: String
displayName: PLN
required: false
- value: QAR
type: String
displayName: QAR
required: false
- value: RON
type: String
displayName: RON
required: false
- value: RSD
type: String
displayName: RSD
required: false
- value: RUB
type: String
displayName: RUB
required: false
- value: RWF
type: String
displayName: RWF
required: false
- value: SAR
type: String
displayName: SAR
required: false
- value: SCR
type: String
displayName: SCR
required: false
- value: SEK
type: String
displayName: SEK
required: false
- value: SGD
type: String
displayName: SGD
required: false
- value: THB
type: String
displayName: THB
required: false
- value: TND
type: String
displayName: TND
required: false
- value: TRY
type: String
displayName: TRY
required: false
- value: TTD
type: String
displayName: TTD
required: false
- value: TWD
type: String
displayName: TWD
required: false
- value: TZS
type: String
displayName: TZS
required: false
- value: UAH
type: String
displayName: UAH
required: false
- value: UGX
type: String
displayName: UGX
required: false
- value: USD
type: String
displayName: USD
required: false
- value: UYU
type: String
displayName: UYU
required: false
- value: VEF
type: String
displayName: VEF
required: false
- value: VND
type: String
displayName: VND
required: false
- value: VUV
type: String
displayName: VUV
required: false
- value: XAF
type: String
displayName: XAF
required: false
- value: XCD
type: String
displayName: XCD
required: false
- value: XOF
type: String
displayName: XOF
required: false
- value: ZAR
type: String
displayName: ZAR
required: false
- value: ZMK
type: String
displayName: ZMK
required: false
required: true
balance:
type: Number
displayName: Balance
description: The balance of the bank account
required: false
validation:
warnings: []
information:
- field: Balance
details: 'The opening balance, in the account currency'
institution:
type: String
displayName: Institution
description: The institution of the bank account
required: false
required: true
KashFlow:
value:
type: Object
displayName: Bank Account
description: An account that bank transactions may be recorded against
properties:
accountName:
type: String
displayName: Account Name
description: Name of the bank account as it appears in Kashflow.
required: true
balance:
type: Number
displayName: Balance
description: 'The opening balance, in the account currency.'
required: false
currency:
type: String
displayName: Currency
description: The currency of the bank account.
required: true
required: true
QuickBooks Desktop:
value:
type: Object
displayName: Bank Account
description: An account that bank transactions may be recorded against
properties:
nominalCode:
type: String
displayName: Nominal Code
description: The external reference given to each nominal account for a business
required: true
validation:
warnings:
- field: NominalCode
details: Max length of 7 characters.
information: []
accountName:
type: String
displayName: Name
description: The name of the bank account in the originating system
required: true
validation:
warnings:
- field: AccountName
details: Max length of 31 characters.
information: []
currency:
type: String
displayName: Currency
description: The currency of the bank account
required: false
validation:
warnings:
- field: Currency
details: 'The currency must match the base currency of the QuickBooks Desktop company unless the FullyQualifiedCategory is ''Asset.AccountsReceivable'',''Liability.AccountsPayable'' or ''Liability.CreditCard'''
- field: Currency
details: Must be a three letter ISO code that matches an existing active currency in the QuickBooks Desktop company
- field: Currency
details: Can only be set if the Quickbooks Desktop company has Multicurrency enabled.
information:
- field: Currency
details: 'If not set, will default to the base currency of the QuickBooks Desktop company'
balance:
type: Number
displayName: Balance
description: The balance of the bank account
required: false
required: true
QuickBooks Online Sandbox:
value:
type: Object
displayName: Bank Account
description: An account that bank transactions may be recorded against
properties:
accountName:
type: String
displayName: Account Name
description: Name of account as it appears in the chart of accounts or general ledger.
required: true
accountNumber:
type: String
displayName: Account Number
description: User-defined account number to help the user in identifying the account within the chart-of-accounts and in deciding what should be posted to the account.
required: true
currency:
type: String
displayName: Currency
description: Currency of the bank account.
required: true
required: true
Sage Business Cloud Accounting:
value:
type: Object
displayName: Bank Account
description: An account that bank transactions may be recorded against
properties:
accountName:
type: String
displayName: Name
description: The name of the bank account in the originating system
required: true
validation:
warnings: []
information:
- field: AccountName
details: Must be provided.
- field: AccountName
details: Should not be longer than 50 characters.
currency:
type: String
displayName: Currency
description: The currency of the bank account
required: true
validation:
warnings: []
information:
- field: Currency
details: Must be provided.
- field: Currency
details: Must match the company's base currency.
sortCode:
type: String
displayName: Sort Code
description: The sort code for the bank account
required: false
validation:
warnings: []
information:
- field: SortCode
details: Should be a 6 digit number.
accountNumber:
type: String
displayName: Account Number
description: The account number for the bank account
required: false
validation:
warnings: []
information:
- field: AccountNumber
details: Should not be longer than 25 characters.
iBan:
type: String
displayName: IBAN
description: The international bank account number of the account. Often used when making or receiving international payments
required: false
validation:
warnings: []
information:
- field: IBan
details: Should be in the international bank account number format.
nominalCode:
type: String
displayName: Nominal Code
description: The external reference given to each nominal account for a business
required: false
validation:
warnings: []
information:
- field: NominalCode
details: Should be a number between 1 and 99999999.
required: true
Sandbox:
value:
type: Object
displayName: Bank Account
description: An account that bank transactions may be recorded against
properties:
accountName:
type: String
displayName: Name
description: The name of the bank account in the originating system
required: true
accountType:
type: String
displayName: Account Type
description: The type of account
required: true
nominalCode:
type: String
displayName: Nominal Code
description: The external reference given to each nominal account for a business
required: true
sortCode:
type: String
displayName: Sort Code
description: The sort code for the bank account
required: true
accountNumber:
type: String
displayName: Account Number
description: The account number for the bank account
required: true
iBan:
type: String
displayName: IBAN
description: The international bank account number of the account. Often used when making or receiving international payments
required: true
currency:
type: String
displayName: Currency
description: The currency of the bank account
required: true
balance:
type: Number
displayName: Balance
description: The balance of the bank account
required: true
availableBalance:
type: Number
displayName: Available Balance
description: The available balance of the bank account
required: true
overdraftLimit:
type: Number
displayName: Overdraft Limit
description: The pre-arranged overdraft limit of the account
required: true
institution:
type: String
displayName: Institution
description: The institution of the bank account
required: true
metadata:
type: Object
displayName: Metadata
description: Miscellaneous data about the item
properties:
isDeleted:
type: Boolean
displayName: IsDeleted
description: A boolean to indicate whether the object has been deleted
required: true
required: true
required: true
'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-create-bankAccounts-model
description: "The *Get create/update bank account model* endpoint returns the expected data for the request payload when creating and updating a [bank account](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) for a given company and integration.\r\n\r\n[Bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution.\r\n\r\n**Integration-specific behaviour**\r\n\r\nSee the *response examples* for integration-specific indicative models.\r\n\r\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=bankAccounts) for integrations that support creating and updating a bank account.\r\n"
'/companies/{companyId}/connections/{connectionId}/push/bankAccounts':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
post:
x-internal: true
tags:
- Bank accounts
summary: Create bank account
parameters:
- $ref: '#/components/parameters/timeoutInMinutes'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccounts/allOf/0/properties/results/items/definitions/bankAccountPrototype'
examples: {}
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccounts/allOf/0/properties/results/items/definitions/bankAccountCreateResponse'
examples: {}
'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'
description: "The *Create bank account* endpoint creates a new [bank account](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) for a given company's connection.\r\n\r\n[Bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution.\r\n\r\n**Integration-specific behaviour**\r\n\r\nRequired data may vary by integration. To see what data to post, first call [Get create/update bank account model](https://docs.codat.io/bank-feeds-api#/operations/get-create-update-bankAccounts-model).\r\n\r\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=bankAccounts) for integrations that support creating an account."
operationId: create-bank-account
'/companies/{companyId}/connections/{connectionId}/connectionInfo/bankFeedAccounts':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
post:
tags:
- Source accounts
summary: Create source account
description: |-
The _Create Source Account_ endpoint allows you to create a representation of a bank account within Codat's domain. The company can then map the source account to an existing or new target account in their accounting software.
#### Account mapping variability
The method of mapping the source account to the target account varies depending on the accounting software your company uses.
#### Mapping options:
1. **API Mapping**: Integrate the mapping journey directly into your application for a seamless user experience.
2. **Codat UI Mapping**: If you prefer a quicker setup, you can utilize Codat's provided user interface for mapping.
3. **Accounting Platform Mapping**: For some accounting software, the mapping process must be conducted within the software itself.
### Integration-specific behaviour
| Bank Feed Integration | API Mapping | Codat UI Mapping | Accounting Platform Mapping |
| --------------------- | ----------- | ---------------- | --------------------------- |
| Xero | ✅ | ✅ | |
| FreeAgent | ✅ | ✅ | |
| Oracle NetSuite | ✅ | ✅ | |
| Exact Online (NL) | ✅ | ✅ | |
| QuickBooks Online | | | ✅ |
| Sage | | | ✅ |
> ### Versioning
> If you are integrating the Bank Feeds API with Codat after August 1, 2024, please use the v2 version of the API, as detailed in the schema below. For integrations completed before August 1, 2024, select the v1 version from the schema dropdown below.
operationId: create-source-account
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SourceAccountV2'
- $ref: '#/components/schemas/SourceAccount'
examples: {}
responses:
'200':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SourceAccountV2'
- $ref: '#/components/schemas/SourceAccount'
examples: {}
'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'
get:
tags:
- Source accounts
summary: List source accounts
description: "\uFEFFThe _List source accounts_ endpoint returns a list of [source accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankFeedAccount) for a given company's connection.\n\n[source accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankFeedAccount) are the bank's bank account within Codat's domain from which transactions are synced into the accounting platform.\n\n> ### Versioning\n> If you are integrating the Bank Feeds API with Codat after August 1, 2024, please use the v2 version of the API, as detailed in the schema below. For integrations completed before August 1, 2024, select the v1 version from the schema dropdown below."
operationId: list-source-accounts
responses:
'200':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SourceAccountV2/definitions/sourceAccounts'
- $ref: '#/components/schemas/SourceAccount/definitions/sourceAccounts'
examples: {}
'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'
'/companies/{companyId}/connections/{connectionId}/connectionInfo/bankFeedAccounts/{accountId}':
patch:
tags:
- Source accounts
summary: Update source account
description: "\uFEFFThe _Update source account_ endpoint updates a single source account for a single data connection connected to a single company.\n\n### Tips and pitfalls\n\n* This endpoint only updates the `accountName` field.\n* Updates made here apply exclusively to source accounts and will not affect target accounts in the accounting software."
operationId: update-source-account
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/accountId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SourceAccount'
examples: {}
responses:
'200':
description: Success
content:
application/json:
x-speakeasy-usage-example: true
schema:
$ref: '#/components/schemas/SourceAccount'
examples: {}
'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'
delete:
tags:
- Source accounts
summary: Delete source account
description: |
The _Delete source account_ endpoint enables you to remove a source account.
Removing a source account will also remove any mapping between the source bank feed bank accounts and the target bankfeed bank account.
operationId: delete-source-account
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/accountId'
responses:
'204':
description: No Content
'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'
'/companies/{companyId}/connections/{connectionId}/connectionInfo/bankFeedAccounts/credentials':
post:
tags:
- Source accounts
summary: Generate source account credentials
description: "\uFEFFThe _Generate bank account credentials_ endpoint can be used to generate credentials for QuickBooks Online to authenticate the Bank Feed in the QBO portal. Each time this endpoint is called, a new set of credentials will be generated.\n\nThe old credentials will still be valid until the revoke credentials endpoint is used, which will revoke all credentials associated to the data connection.\n\n> **For QuickBooks Online only**\n>\n> Only call this endpoint when onboarding SMBs that use QuickBooks Online."
operationId: generate-credentials
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
requestBody:
required: true
content:
application/json: {}
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccountCredentials'
'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'
delete:
tags:
- Source accounts
summary: Delete all source account credentials
x-speakeasy-name-override: delete-credentials
description: |-
The _Delete Bank Account Credentials_ endpoint serves as a comprehensive mechanism for revoking all existing authorization credentials that a company employs to establish its Bank Feed connection.
In cases where multiple credential sets have been generated, a single API call to this endpoint revokes all of them.
operationId: delete-bank-feed-credentials
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
responses:
'204':
description: No Content
'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'
'/companies/{companyId}/connections/{connectionId}/bankFeedAccounts/mapping':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
tags:
- Account mapping
summary: List bank feed accounts
description: "\uFEFFThe *List bank accounts* endpoint returns information about a source bank account and any current or potential target mapping accounts.\n\nA bank feed account mapping is a specified link between the source account (provided by the Codat user) and the target account (the end user's account in the underlying software).\n\n> **For custom builds only**\n> \n> Only use this endpoint if you are building your own account management UI."
operationId: get-bank-account-mapping
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BankFeedMapping/definitions/bankFeedMappings'
examples:
Example:
value:
- sourceAccountId: account-001
status: pending
targetAccountOptions:
- name: Money Bank account
id: d21e25d6-98c5-4bfb-b469-105833bea3c8
accountNumber: '789'
sortCode: '123456'
- name: Bank of Dave account
id: d06ff4b2-e4f2-4681-9841-014bd008cdab
accountNumber: '99887766'
sortCode: '998866'
- name: LuxLend account
id: c8f252fc-84f3-4a8b-ace8-ae99f41a81ae
accountNumber: '123456789'
sortCode: '123456'
sourceAccountName: account-001
sourceAccountNumber: '12345670'
sourceBalance: 99.99
sourceCurrency: GBP
'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'
post:
tags:
- Account mapping
summary: Create bank feed account mapping
description: "\uFEFFThe *Create bank account mapping* endpoint creates a new mapping between a source bank account and a potential account in the accounting software (target account).\n\nA bank feed account mapping is a specified link between the source account (provided by the Codat user) and the target account (the end user's account in the underlying software).\n\nTo find valid target account options, first call the [List bank feed account mappings](https://docs.codat.io//bank-feeds-api#/operations/get-bank-account-mapping) endpoint.\n\n> **For custom builds only**\n>\n> Only use this endpoint if you are building your own account management UI."
operationId: create-bank-account-mapping
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BankFeedAccountMapping'
examples:
Example:
value:
sourceAccountId: acc-002
targetAccountId: account-081
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BankFeedAccountMappingResponse'
examples: {}
'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'
'/companies/{companyId}/connections/{connectionId}/bankFeeds/info':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get company information
description: |+
Use the *Get company information* endpoint to return information about the company available from the underlying accounting software.
operationId: get-company-information
tags:
- Company information
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyInformation'
examples: {}
'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'
'/companies/{companyId}/connections/{connectionId}/push/bankAccounts/{accountId}/bankTransactions':
post:
tags:
- Transactions
summary: Create bank transactions
description: "\uFEFFThe *Create bank transactions* endpoint creates new [bank transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) for a given company's connection.\n\n[Bank transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) are records of monetary amounts that have moved in and out of an SMB's bank account.\n\n**Integration-specific behaviour**\n\nRequired data may vary by integration. To see what data to post, first call [Get create bank transaction model](https://docs.codat.io/bank-feeds-api#/operations/get-create-bankTransactions-model).\n\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=bankTransactions) for integrations that support creating a bank account transactions.\n"
operationId: create-bank-transactions
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/timeoutInMinutes'
- name: allowSyncOnPushComplete
in: query
schema:
type: boolean
default: true
description: Allow a sync upon push completion.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBankTransactions'
examples:
Xero:
value:
accountId: 49cd5a42-b311-4750-9361-52e2ed1d4653
transactions:
- id: '716422529'
date: '2023-08-22T10:21:00Z'
description: Repayment of Credit Card
counterparty: Bank of Example
reference: Ref-12345
reconciled: true
amount: 100
balance: 100
transactionType: Credit
- id: '716422530'
date: '2023-08-22T10:22:00Z'
description: Amazon Purchase
counterparty: Amazon
reference: Ref-12346
reconciled: false
amount: -100
balance: 0
transactionType: Debit
- id: '716422531'
date: '2023-08-22T10:23:00Z'
description: Office Supplies
counterparty: Office Mart
reference: Ref-12347
reconciled: false
amount: -60
balance: -60
transactionType: Debit
QuickBooks Online Bank Feeds:
value:
accountId: 49cd5a42-b311-4750-9361-52e2ed1d4653
transactions:
- id: '716422529'
date: '2023-08-22T10:21:00Z'
description: Repayment of Credit Card
amount: 100
balance: 100
transactionType: Credit
- id: '716422530'
date: '2023-08-22T10:22:00Z'
description: Amazon Purchase
amount: -100
balance: 0
transactionType: Debit
- id: '716422531'
date: '2023-08-22T10:23:00Z'
description: Office Supplies
amount: -60
balance: -60
transactionType: Debit
FreeAgent:
value:
accountId: 49cd5a42-b311-4750-9361-52e2ed1d4653
transactions:
- id: '716422529'
date: '2023-08-22T10:21:00Z'
description: Repayment of Credit Card
amount: 100
transactionType: Credit
- id: '716422530'
date: '2023-08-22T10:22:00Z'
description: Amazon Purchase
amount: -100
transactionType: Debit
- id: '716422531'
date: '2023-08-22T10:23:00Z'
description: Office Supplies
amount: -60
transactionType: Debit
Sage:
value:
accountId: 49cd5a42-b311-4750-9361-52e2ed1d4653
transactions:
- id: '716422529'
date: '2023-08-22T10:21:00Z'
description: Repayment of Credit Card
counterparty: Bank of Example
reference: Ref-12345
amount: 100
balance: 100
transactionType: Credit
- id: '716422530'
date: '2023-08-22T10:22:00Z'
description: Amazon Purchase
counterparty: Amazon
reference: Ref-12346
amount: -100
balance: 0
transactionType: Debit
- id: '716422531'
date: '2023-08-22T10:23:00Z'
description: Office Supplies
counterparty: Office Mart
reference: Ref-12347
amount: -60
balance: -60
transactionType: Debit
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBankTransactionsResponse'
'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'
'/companies/{companyId}/push/{pushOperationKey}':
parameters:
- $ref: '#/components/parameters/companyId'
- schema:
type: string
format: uuid
name: pushOperationKey
in: path
required: true
description: Push operation key.
get:
summary: Get create operation
tags:
- Transactions
operationId: get-create-operation
x-speakeasy-name-override: get-create-operation
description: |-
The **Get create operation** endpoint returns a specific [write operation](/using-the-api/push) identified by the `pushOperationKey` that was performed on the company.
Write operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software.
For bank feeds, your push operations will only relate to the `bankTransactions` data type.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PushOperation'
examples: {}
'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'
'/companies/{companyId}/push':
parameters:
- $ref: '#/components/parameters/companyId'
get:
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
summary: List create operations
tags:
- Transactions
operationId: list-create-operations
x-speakeasy-name-override: list-create-operations
description: |-
The **List create operations** endpoint returns a list of [write operations](/using-the-api/push) performed on the company.
Write operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software.
For bank feeds, use this endpoint to view write operations related to the `bankTransactions` data type.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PushOperations'
examples: {}
'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'
webhooks:
client.rateLimit.reached:
post:
description: Called when your client’s request count to Codat's API surpasses the allocated quota.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClientRateLimitWebhook'
examples:
Reached:
value:
id: 743ec94a-8aa4-44bb-8bd4-e1855ee0e74b
eventType: client.rateLimit.reached
generatedDate: '2024-09-01T00:00:00Z'
payload:
dailyQuota: 12000
quotaRemaining: 0
expiryDate: '2024-09-01T12:14:14Z'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
client.rateLimit.reset:
post:
description: 'Called when your client''s rate limit quota is reset, allowing additional requests to Codat''s API.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClientRateLimitWebhook'
examples:
Reset:
value:
id: 743ec94a-8aa4-44bb-8bd4-e1855ee0e74b
eventType: client.rateLimit.reset
generatedDate: '2024-09-01T00:00:00Z'
payload:
dailyQuota: 12000
quotaRemaining: 11993
expiryDate: '2024-09-01T23:59:99Z'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
Client rate limit reached:
post:
deprecated: true
description: |-
Called when your client’s requests to Codat's API exceed the allocated quota.
**Note: This event type is deprecated. Developers should now use the `client.rateLimit.reached` event for handling rate limit notifications.**
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClientRateLimitReachedWebhook'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
Client rate limit reset:
post:
deprecated: true
description: |-
Called when the rate limit quota has reset for the client, and more requests to Codat's API are available.
Note: This event type is deprecated. Developers should now use the `client.rateLimit.reset` event for handling rate limit notifications.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClientRateLimitResetWebhook'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
bankFeeds.sourceAccount.connected:
post:
description: Called when a bank feed source account has become connected.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SourceAccountWebhook'
examples:
Connected:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
eventType: bankFeeds.sourceAccount.connected
generatedDate: 2022-10-23T00:00:00.000Z
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Toft stores
description: Requested early access to the new financing scheme.
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
connectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
sourceAccount:
id: acc-002
accountName: account-081
sortCode: '040004'
accountNumber: '12345678'
currency: GBP
balance: 99.99
modifiedDate: 2023-01-09T14:14:14.105Z
status: pending
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
bankFeeds.sourceAccount.disconnected:
post:
description: Called when a bank feed source account has become disconnected.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SourceAccountWebhook'
examples:
Disconnected:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
eventType: bankFeeds.sourceAccount.disconnected
generatedDate: 2022-10-23T00:00:00.000Z
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Toft stores
description: Requested early access to the new financing scheme.
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
connectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
sourceAccount:
id: acc-002
accountName: account-081
sortCode: '040004'
accountNumber: '12345678'
currency: GBP
balance: 99.99
modifiedDate: 2023-01-09T14:14:14.105Z
status: pending
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
components:
schemas:
BankAccountCredentials:
title: Bank Account Credentials
description: Result of generate credentials
type: object
properties:
username:
type: string
example: S0MW-TR0P-7DS0
description: Username used by the bank feeds platform to retrieve transactions
password:
type: string
example: cO0ajh0uGyTN0Pwh
description: Password to enable the bank feeds platform to securely retrieve transactions.
examples:
QuickBooks Online Bank Feeds:
username: S0MW-TR0P-7DS0
password: cO0ajh0uGyTN0Pwh
BankAccounts:
x-internal: true
title: 'Accounting: Bank accounts'
allOf:
- type: object
properties:
results:
type: array
items:
title: 'Accounting: Bank account'
description: |-
> **Accessing Bank Accounts through Banking API**
>
> This datatype was originally used for accessing bank account data both in accounting integrations and open banking aggregators.
>
> To view bank account data through the Banking API, please refer to the new datatype [here](https://docs.codat.io/bank-feeds-api#/schemas/Account)
> View the coverage for bank accounts in the Data coverage explorer.
## Overview
A list of bank accounts associated with a company and a specific data connection.
Bank accounts data includes:
* The name and ID of the account in the accounting software.
* The currency and balance of the account.
* The sort code and account number.
type: object
allOf:
- properties:
id:
type: string
description: 'Identifier for the account, unique for the company in the accounting software.'
- $ref: '#/components/schemas/BankAccounts/allOf/0/properties/results/items/definitions/bankAccountPrototype'
- properties:
metadata:
title: Metadata
type: object
x-internal: true
properties:
isDeleted:
type: boolean
description: Indicates whether the record has been deleted in the third-party system this record originated from.
nullable: true
supplementalData:
title: Supplemental data
type: object
x-internal: true
description: |-
Supplemental data is additional data you can include in our standard data types.
It is referenced as a configured dynamic key value pair that is unique to the accounting software. [Learn more](https://docs.codat.io/using-the-api/supplemental-data/overview) about supplemental data.
properties:
content:
type: object
additionalProperties:
type: object
additionalProperties: true
nullable: true
- title: Modified dates
x-internal: true
allOf:
- title: ModifiedDate
x-internal: true
type: object
properties:
modifiedDate:
allOf:
- $ref: '#/components/schemas/DateTime'
- description: |-
The date when the record was last fetched from the data source and updated in Codat’s data cache.
Use it to identify and retrieve records that have changed since your last fetch. For example, filtering `modifiedDate` to today will provide new records updated in Codat today.
This date is populated for all data types except for attachments, balance sheets, company information, and profit & loss reports ([read more](https://docs.codat.io/using-the-api/modified-dates#modified-date)).
In Codat's data model, dates and times are represented using the ISO 8601 standard.
- title: Source Modified Date
x-internal: true
type: object
nullable: true
properties:
sourceModifiedDate:
allOf:
- $ref: '#/components/schemas/DateTime'
- description: |-
The date when a record was last modified in the source platform, usually by the business or a business process. For example, when payments are made against an invoice.
It is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when:
- Pulling attachments
- The integration platform does not provide modification dates for a data type
- A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred
- A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records
In Codat's data model, dates and times are represented using the ISO 8601 standard.
definitions:
bankAccountPrototype:
title: Bank account prototype
type: object
properties:
accountName:
type: string
nullable: true
description: Name of the bank account in the accounting software.
accountType:
title: Bank Account Type
x-internal: true
enum:
- Unknown
- Credit
- Debit
type: string
description: |-
The type of transactions and balances on the account.
For Credit accounts, positive balances are liabilities, and positive transactions **reduce** liabilities.
For Debit accounts, positive balances are assets, and positive transactions **increase** assets.
nominalCode:
type: string
nullable: true
description: Code used to identify each nominal account for a business.
sortCode:
type: string
nullable: true
description: |-
Sort code for the bank account.
Xero integrations
The sort code is only displayed when the currency = GBP and the sort code and account number sum to 14 digits. For non-GBP accounts, this field is not populated.
accountNumber:
type: string
nullable: true
description: |-
Account number for the bank account.
Xero integrations
Only a UK account number shows for bank accounts with GBP currency and a combined total of sort code and account number that equals 14 digits, For non-GBP accounts, the full bank account number is populated.
FreeAgent integrations
For Credit accounts, only the last four digits are required. For other types, the field is optional.
iBan:
type: string
nullable: true
description: International bank account number of the account. Often used when making or receiving international payments.
currency:
$ref: '#/components/schemas/SourceAccount/properties/currency'
description: Base currency of the bank account.
balance:
type: number
format: decimal
nullable: true
description: Balance of the bank account.
institution:
type: string
nullable: true
description: The institution of the bank account.
availableBalance:
type: number
format: decimal
nullable: true
description: Total available balance of the bank account as reported by the underlying data source. This may take into account overdrafts or pending transactions for example.
overdraftLimit:
type: number
format: decimal
nullable: true
description: |-
Pre-arranged overdraft limit of the account.
The value is always positive. For example, an overdraftLimit of `1000` means that the balance of the account can go down to `-1000`.
status:
$ref: '#/components/schemas/BankAccounts/allOf/0/properties/results/items/definitions/bankAccountStatus'
bankAccountCreateResponse:
title: Create bank account response
allOf:
- properties:
data:
allOf:
- $ref: '#/components/schemas/BankAccounts/allOf/0/properties/results/items'
- deprecated: true
- $ref: '#/components/schemas/PushOperation'
bankAccountRef:
title: Bank account reference
type: object
properties:
id:
type: string
description: Bank account 'id' for the account transaction.
name:
type: string
description: bank account 'name' for the account transaction.
description: Links to the Account transactions data type.
bankAccounts:
title: 'Accounting: Bank accounts'
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/BankAccounts/allOf/0/properties/results/items'
- $ref: '#/components/schemas/Companies/allOf/1'
bankAccountStatus:
title: Account status
enum:
- Unknown
- Active
- Archived
- Pending
type: string
description: Status of the bank account.
example: Active
- $ref: '#/components/schemas/Companies/allOf/1'
BankFeedAccountMapping:
title: Bank feed account mapping
type: object
additionalProperties: false
properties:
sourceAccountId:
type: string
description: Unique ID for the source account
targetAccountId:
type: string
nullable: true
description: Unique ID for the target account
required:
- sourceAccountId
examples:
- sourceAccountId: acc-002
targetAccountId: account-081
BankFeedAccountMappingResponse:
title: Bank feed account mapping response
type: object
additionalProperties: false
properties:
sourceAccountId:
type: string
description: Unique ID for the source account.
targetAccountId:
type: string
nullable: true
description: Unique ID for the target account.
status:
type: string
nullable: true
description: Status of the POST request.
error:
type: string
nullable: true
description: Error returned during the post request
examples:
- sourceAccountId: acc-002
targetAccountId: account-081
status: Failed
error: A feed connection already exists to this account
BankFeedMapping:
title: Bank feed mapping
type: object
additionalProperties: false
properties:
sourceAccountId:
type: string
description: Unique ID for the source account.
sourceAccountName:
type: string
description: Name for the source account.
sourceAccountNumber:
type: string
description: Account number for the source account.
sourceBalance:
type: string
description: Balance for the source account.
sourceCurrency:
$ref: '#/components/schemas/SourceAccount/properties/currency'
targetAccountId:
type: string
nullable: true
description: Unique ID for the target account in the accounting software.
targetAccountName:
type: string
description: Name for the target account in the accounting software.
status:
type: string
description: The status.
targetAccountOptions:
type: array
nullable: true
description: An array of potential target accounts.
items:
$ref: '#/components/schemas/BankFeedMapping/definitions/targetAccountOption'
feedStartDate:
$ref: '#/components/schemas/DateTime'
nullable: true
description: The date from which bank transactions can be provided to the platform.
description: 'A bank feed connection between a source account and a target account, including potential target accounts.'
definitions:
targetAccountOption:
title: Target Account Option
type: object
properties:
id:
type: string
description: Id of the target account.
name:
type: string
nullable: true
description: Name of the target account.
balance:
type: number
format: decimal
nullable: true
description: The balance of the account.
sortCode:
type: string
nullable: true
description: The sort code of the account.
accountNumber:
type: string
nullable: true
description: The account number of the account.
bankFeedMappings:
title: Bank feed mappings
type: array
items:
$ref: '#/components/schemas/BankFeedMapping'
additionalProperties: false
examples:
- sourceAccountId: acc-002
targetAccountId: account-081
sourceCurrency: USD
status: Success
feedStartDate: '2023-01-09T14:14:14.1057478Z'
sourceAccountName: ACME Bank
sourceAccountNumber: 1234-5678
sourceBalance: 500
targetAccountName: ACME Bank
- sourceAccountId: c53fd75a-dddb-4493-839a-5090b008f625
status: pending
targetAccountOptions:
- name: account-081
id: 044096a7-1478-4554-8820-f478caad1b00
balance: 100.99
sortCode: '602336'
accountNumber: '23203'
sourceAccountName: bank name here
sourceAccountNumber: '5670'
sourceBalance: 1550
sourceCurrency: GBP
BankTransactions:
title: Bank transactions
type: array
maxItems: 1000
items:
title: Bank transaction
type: object
properties:
id:
type: string
description: 'Identifier for the bank account transaction, unique for the company in the accounting software.'
example: '716422529'
date:
$ref: '#/components/schemas/DateTime'
description:
type: string
nullable: true
description: Description of the bank transaction.
example: Debit for Payment Id sdp-1-57379a43-c4b8-49f5-bd7c-699189ee7a60
counterparty:
type: string
nullable: true
description: The giving or receiving party such as a person or organization.
example: ACME INC
reference:
type: string
nullable: true
description: An optional reference to the bank transaction.
example: reference for transaction
reconciled:
type: boolean
nullable: true
description: '`True` if the bank transaction has been [reconciled](https://www.xero.com/uk/guides/what-is-bank-reconciliation/) in the accounting software.'
example: false
amount:
type: number
format: decimal
description: The amount transacted in the bank transaction.
example: 999.99
balance:
type: number
format: decimal
description: 'The remaining balance in the account with ID `accountId`. This field is optional for QuickBooks Online but is required for Xero, Sage, NetSuite, Exact, and FreeAgent.'
example: -999.99
transactionType:
title: Bank transaction type
nullable: true
description: Type of transaction for the bank statement line.
type: string
enum:
- Unknown
- Credit
- Debit
- Int
- Div
- Fee
- SerChg
- Dep
- Atm
- Pos
- Xfer
- Check
- Payment
- Cash
- DirectDep
- DirectDebit
- RepeatPmt
- Other
required:
- id
- date
- amount
ClientRateLimitReachedWebhook:
title: Client rate limit reached webhook
x-internal: true
description: Webhook request body for a client that has reached their rate limit.
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/ClientId'
ClientName:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/ClientName'
RuleId:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/Message'
Data:
$ref: '#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData'
definitions:
ClientRateLimitReachedWebhookData:
type: object
title: Client rate limit reached webhook data
properties:
DailyQuota:
type: integer
description: The number of available requests per day.
ExpiresUtc:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC when your daily quota is reset.
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Rate Limit Reached
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: The current daily rate limit quota of 1000 requests for bae71d36-ff47-420a-b4a6-f8c9ddf41140 has been reached.
Data:
DailyQuota: 1000
ExpiresUtc: '2023-05-03T00:00:00Z'
ClientRateLimitResetWebhook:
title: Client rate limit reset webhook
x-internal: true
description: Webhook request body for a client that has had their rate limit reset.
type: object
properties:
ClientId:
title: Client ID
type: string
format: uuid
description: Unique identifier for your client in Codat.
ClientName:
type: string
description: Name of your client in Codat.
RuleId:
type: string
format: uuid
description: Unique identifier for the rule.
deprecated: true
RuleType:
type: string
x-stoplight:
id: 34d52a089f08a
description: The type of rule.
AlertId:
type: string
format: uuid
description: Unique identifier of the webhook event.
Message:
type: string
description: A human-readable message about the webhook.
Data:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/definitions/ClientRateLimitResetWebhookData'
definitions:
ClientRateLimitResetWebhookData:
type: object
title: Client rate limit reset webhook data
properties:
QuotaRemaining:
type: integer
description: Total number of requests remaining for your client.
nullable: true
ResetReason:
type: string
description: The reason for your rate limit quota being reset.
DailyQuota:
$ref: '#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/DailyQuota'
nullable: true
ExpiresUtc:
$ref: '#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/ExpiresUtc'
nullable: true
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Rate Limit Reset
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: The current daily rate limit quota for client 30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e has been reset to 1000 requests.
Data:
QuotaRemaining: 1000
ResetReason: The quota was reset because it is a new day.
DailyQuota: 1000
ExpiresUtc: '2023-05-03T00:00:00Z'
ClientRateLimitWebhook:
title: Client rate limit webhook
type: object
properties:
id:
type: string
format: uuid
example: 743ec94a-8aa4-44bb-8bd4-e1855ee0e74b
description: Unique identifier of the event.
eventType:
type: string
description: The type of event.
examples:
- client.rateLimit.reset
- client.rateLimit.reached
generatedDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC the event was generated in Codat.
payload:
$ref: '#/components/schemas/ClientRateLimitWebhook/definitions/clientRateLimitWebhookPayload'
definitions:
clientRateLimitWebhookPayload:
title: Client rate limit webhook payload
type: object
properties:
dailyQuota:
type: integer
description: The number of available requests per day.
quotaRemaining:
type: integer
description: Total number of requests remaining for your client.
expiryDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC when your daily quota is reset.
Companies:
title: Companies
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Company'
- type: object
title: Pagination information
x-internal: true
properties:
pageNumber:
type: integer
description: Current page number.
pageSize:
type: integer
description: Number of items to return in results array.
maximum: 2000
totalResults:
type: integer
description: Total number of items.
_links:
$ref: '#/components/schemas/Companies/allOf/1/definitions/links'
definitions:
links:
title: Hal Links
type: object
required:
- self
- current
properties:
self:
$ref: '#/components/schemas/Companies/allOf/1/definitions/halRef'
current:
$ref: '#/components/schemas/Companies/allOf/1/definitions/halRef'
next:
$ref: '#/components/schemas/Companies/allOf/1/definitions/halRef'
previous:
$ref: '#/components/schemas/Companies/allOf/1/definitions/halRef'
examples:
- self:
href: /companies
current:
href: /companies?page=1&pageSize=10
halRef:
title: Hypertext reference
type: object
properties:
href:
type: string
format: uri-reference
description: Uri hypertext reference.
required:
- pageNumber
- pageSize
- totalResults
- _links
examples:
- pageNumber: 1
pageSize: 10
totalResults: 1
_links:
self:
href: '/companies/{id}/data/{dataType}'
current:
href: '/companies/{id}/data/{dataType}?page=1&pageSize=10'
Company:
title: Company
description: "\uFEFFIn Codat, a company represents a business sharing access to their data. Each company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources such as one connection to [Xero](https://docs.codat.io/integrations/accounting/xero/accounting-xero) for accounting data, two connections to [Plaid](https://docs.codat.io/integrations/banking/plaid/banking-plaid) for two bank accounts and a connection to [Zettle](https://docs.codat.io/integrations/commerce/zettle/commerce-zettle) for POS data.\n\nTypically each company is one of your customers.\n\nWhen you create a company, you can specify a `name` and we will automatically generate a unique `id` for the company. You can also add a `description` to store any additional information about the company."
type: object
allOf:
- $ref: '#/components/schemas/Company/definitions/companyDetails'
- type: object
properties:
dataConnections:
type: array
items:
$ref: '#/components/schemas/Connection'
definitions:
companyDetails:
title: Company details
type: object
properties:
id:
$ref: '#/components/parameters/companyId/schema'
name:
type: string
description: The name of the company
example: Codat Ltd.
description:
$ref: '#/components/schemas/CompanyRequestBody/properties/description'
nullable: true
redirect:
type: string
format: uri
description: 'The `redirect` [Link URL](https://docs.codat.io/auth-flow/authorize-hosted-link) enabling the customer to start their auth flow journey for the company.'
example: 'https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739'
lastSync:
$ref: '#/components/schemas/DateTime'
nullable: true
created:
$ref: '#/components/schemas/DateTime'
createdByUserName:
type: string
description: Name of user that created the company in Codat.
nullable: true
products:
type: array
items:
type: string
description: An array of products that are currently enabled for the company.
tags:
type: object
maxProperties: 10
propertyNames:
pattern: '^.{1,27}$'
additional properties:
type: string
maxLength: 100
description: A collection of user-defined key-value pairs that store custom metadata against the company.
required:
- id
- name
- redirect
companyReference:
title: Company reference
type: object
properties:
id:
$ref: '#/components/parameters/companyId/schema'
name:
$ref: '#/components/schemas/Company/definitions/companyDetails/properties/name'
description:
$ref: '#/components/schemas/Company/definitions/companyDetails/properties/description'
links:
type: object
description: A collection of links for the company.
properties:
portal:
type: string
format: uri
description: Link to the company page in the portal.
tags:
$ref: '#/components/schemas/Company/definitions/companyDetails/properties/tags'
examples:
- id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: string
redirect: 'https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739'
lastSync: '2022-01-01T12:00:00.000Z'
created: '2022-01-01T12:00:00.000Z'
createdByUserName: string
tags:
region: us
uid: f6b0c253-16c7-4da1-a0c5-9c871e9c9d6c
dataConnections:
- id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd
integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c
integrationKey: dfxm
sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee
platformName: Basiq
linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: '2022-10-27T10:22:43.6464237Z'
created: '2022-10-27T09:53:29Z'
sourceType: Banking
CompanyInformation:
title: Company information
description: Information about the company from the underlying accounting software.
type: object
properties:
companyName:
type: string
nullable: false
description: Name of the linked company.
baseCurrency:
type: string
nullable: false
description: Currency set in the accounting software of the linked company.
planType:
type: string
nullable: true
description: 'Accounting software subscription type such as Trial, Demo, Standard'
multicurrencyEnabled:
type: boolean
nullable: true
description: Boolean showing if the organisation has multicurrency enabled
CompanyRequestBody:
title: Create company request
x-internal: true
type: object
properties:
name:
type: string
description: Name of company being connected.
pattern: '^[A-Za-z0-9\s\-'',&@.,?!\s]+$'
minLength: 1
example: Bank of Dave
description:
type: string
example: Requested early access to the new financing scheme.
description: 'Additional information about the company. This can be used to store foreign IDs, references, etc.'
tags:
$ref: '#/components/schemas/Company/definitions/companyDetails/properties/tags'
required:
- name
CompanySyncStatus:
title: Company sync status
type: object
additionalProperties: false
x-examples:
Success Data Pushed:
companyId: 20803807-4e9a-4cb7-b67b-9f889a3916e1
syncId: aa4c9dfd-e945-4424-9628-9e724f14c267
syncStatusCode: 2000
syncStatus: Complete
errorMessage: ''
syncExceptionMessage: ''
syncUtc: '2023-01-24T14:15:22Z'
dataPushed: true
Success No Data Pushed:
companyId: 20803807-4e9a-4cb7-b67b-9f889a3916e1
syncId: aa4c9dfd-e945-4424-9628-9e724f14c267
syncStatusCode: 2040
syncStatus: Complete
errorMessage: ''
syncExceptionMessage: ''
syncUtc: '2023-01-24T14:15:22Z'
dataPushed: false
properties:
companyId:
type: string
description: Unique identifier for your SMB in Codat.
example: d4d73051-ed31-42b6-99f6-d288cd940992
nullable: true
syncId:
type: string
description: Unique identifier of the sync.
example: a6a22aff-a43a-411d-a910-2dae73217cce
nullable: true
syncStatusCode:
type: integer
format: int32
description: Status code of the sync.
example: 2000
syncStatus:
type: string
description: Text status of the sync.
examples:
- Complete
- PushError
- Started
- NotStarted
- Pushing
nullable: true
errorMessage:
type: string
description: Error message of the sync.
nullable: true
syncExceptionMessage:
type: string
description: Exception message of the sync.
nullable: true
syncUtc:
$ref: '#/components/schemas/DateTime'
description: Datetime of the sync.
nullable: true
dataPushed:
type: boolean
description: Boolean of whether the sync resulted in data being pushed.
Configuration:
title: Configuration
type: object
x-internal: true
properties:
companyId:
$ref: '#/components/parameters/companyId/schema'
accountingSoftwareCompanyName:
type: string
description: The company name defined in the accounting software.
enabled:
type: boolean
description: Enabled or disable bank feeds.
configured:
type: boolean
description: True if the company has been configured.
schedule:
$ref: '#/components/schemas/Configuration/definitions/configurationSchedule'
configuration:
$ref: '#/components/schemas/Configuration/definitions/syncConfiguration'
definitions:
configurationSchedule:
title: Configuration schedule
type: object
properties:
selectedFrequency:
type: string
description: The sync frequency.
frequencyOptions:
type: array
items:
type: string
description: The available sync frequencies.
startDate:
type: string
description: The datetime in UTC you want to start syncing from.
syncHourUtc:
type: integer
description: The hour in which the sync is initiated.
timeZoneIanaId:
type: string
description: 'The [IANA](https://www.iana.org/time-zones) time zone ID.'
syncConfiguration:
title: Sync configuration
type: object
properties:
syncAsBankFeeds:
$ref: '#/components/schemas/Configuration/definitions/syncAsBankFeeds'
syncAsExpenses:
$ref: '#/components/schemas/Configuration/definitions/syncAsExpenses'
syncAsBankFeeds:
title: Sync as bank feed
type: object
properties:
enableSync:
type: boolean
description: True if bank feeds sync is enabled.
selectedBankAccountId:
type: string
description: The bank account ID being synced.
bankAccountOptions:
type: array
items:
$ref: '#/components/schemas/Configuration/definitions/bankAccountOption'
syncAsExpenses:
title: Sync as expenses
type: object
properties:
enableSync:
type: boolean
description: True if expense sync is enabled.
supplier:
$ref: '#/components/schemas/Configuration/definitions/configurationSupplier'
customer:
$ref: '#/components/schemas/Configuration/definitions/configurationCustomer'
selectedBankAccountId:
type: string
description: The bank account ID being synced.
bankAccountOptions:
type: array
items:
$ref: '#/components/schemas/Configuration/definitions/bankAccountOption'
bankAccountOption:
title: Bank account option
type: object
properties:
id:
type: string
description: Unique identifier for the bank account.
name:
type: string
description: Name of bank account.
accountType:
type: string
description: The type of account.
configurationSupplier:
title: Supplier configuration
type: object
properties:
selectedSupplierId:
type: string
description: Unique identifier for the supplier.
supplierOptions:
type: array
items:
$ref: '#/components/schemas/Configuration/definitions/configurationContactRef'
configurationCustomer:
title: Customer configuration
type: object
properties:
selectedCustomerId:
type: string
description: Unique identifier for the customer.
customerOptions:
type: array
items:
$ref: '#/components/schemas/Configuration/definitions/configurationContactRef'
configurationContactRef:
title: Supplier/customer reference
type: object
properties:
id:
type: string
description: Unique identifier for the supplier/customer.
name:
type: string
description: The supplier/customer's name.
Connection:
title: Connection
description: "\uFEFFA connection represents a [company's](https://docs.codat.io/bank-feeds-api#/schemas/Company) connection to a data source and allows you to synchronize data (pull and/or push) with that source.\n\nA company can have multiple data connections depending on the type of data source it is connecting to. For example, a single company can link to:\n\n- [Accounting data](https://docs.codat.io/accounting-api/overview) - 1 active connection.\n- [Banking data](https://docs.codat.io/banking-api/overview) - Multiple active connections.\n- [Commerce data](https://docs.codat.io/commerce-api/overview) - Multiple active connections.\nAny combination of accounting, banking, and commerce data connections is allowed.\n\nBefore you can use a data connection to pull or push data, the company must grant you access to their business data by [linking the connection](https://docs.codat.io/auth-flow/overview)."
type: object
properties:
id:
$ref: '#/components/parameters/connectionId/schema'
integrationId:
type: string
format: uuid
example: fd321cb6-7963-4506-b873-e99593a45e30
description: A Codat ID representing the integration.
integrationKey:
type: string
description: A unique four-character ID that identifies the platform of the company's data connection. This ensures continuity if the platform changes its name in the future.
sourceId:
type: string
format: uuid
example: 35b92968-9851-4095-ad60-395c95cbcba4
description: 'A source-specific ID used to distinguish between different sources originating from the same data connection. In general, a data connection is a single data source. However, for TrueLayer, `sourceId` is associated with a specific bank and has a many-to-one relationship with the `integrationId`.'
sourceType:
title: Source Type
description: The type of platform of the connection.
type: string
enum:
- Accounting
- Banking
- BankFeed
- Commerce
- Expense
- Other
- Unknown
example: Accounting
platformName:
type: string
description: Name of integration connected to company.
linkUrl:
type: string
format: uri
description: The link URL your customers can use to authorize access to their business application.
example: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/2e2eb431-c1fa-4dc9-93fa-d29781c12bcd/start'
status:
$ref: '#/components/schemas/Connection/definitions/dataConnectionStatus'
lastSync:
$ref: '#/components/schemas/DateTime'
nullable: true
created:
$ref: '#/components/schemas/DateTime'
dataConnectionErrors:
type: array
nullable: true
items:
$ref: '#/components/schemas/Connection/definitions/dataConnectionError'
connectionInfo:
type: object
nullable: true
additionalProperties:
type: string
additionalProperties: false
required:
- id
- integrationId
- integrationKey
- sourceId
- platformName
- linkUrl
- status
- created
- sourceType
definitions:
dataConnectionStatus:
title: Data connection status
description: The current authorization status of the data connection.
type: string
enum:
- PendingAuth
- Linked
- Unlinked
- Deauthorized
dataConnectionError:
title: Data connection error
type: object
properties:
statusCode:
type: string
description: The HTTP status code returned by the source platform when the error occurred.
statusText:
type: string
description: A non-numeric status code/text returned by the source platform when the error occurred.
errorMessage:
type: string
description: A message about a error returned by Codat.
erroredOnUtc:
$ref: '#/components/schemas/DateTime'
status:
title: Error status
description: The current status of a transient error. Null statuses indicate that the error is not transient.
type: string
nullable: true
enum:
- Active
- Resolved
resolvedOnUtc:
description: The datetime in Utc that the error was resolved.
nullable: true
$ref: '#/components/schemas/DateTime'
dataConnectionSourceType:
title: Source Type
description: The type of platform of the connection.
type: string
enum:
- Accounting
- Banking
- BankFeed
- Commerce
- Expense
- Other
- Unknown
example: Accounting
example:
id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd
integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c
integrationKey: dfxm
sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee
platformName: Basiq
linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: '2022-10-27T10:22:43.6464237Z'
created: '2022-10-27T09:53:29Z'
sourceType: Banking
Connections:
title: Connections
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Connection'
- $ref: '#/components/schemas/Companies/allOf/1'
CreateBankTransactions:
title: Create bank transactions
type: object
properties:
accountId:
type: string
description: Unique identifier for a bank account.
examples:
- 13d946f0-c5d5-42bc-b092-97ece17923ab
- 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2
- '7110701885'
- EILBDVJVNUAGVKRQ
- Checking 0202
transactions:
$ref: '#/components/schemas/BankTransactions'
required:
- accountId
- transactions
CreateBankTransactionsResponse:
title: Create bank transaction response
x-internal: true
allOf:
- type: object
properties:
data:
$ref: '#/components/schemas/CreateBankTransactions'
- $ref: '#/components/schemas/PushOperation'
DataType:
title: Data types
x-internal: true
type: string
description: Available data types
enum:
- accountTransactions
- balanceSheet
- bankAccounts
- bankTransactions
- billCreditNotes
- billPayments
- bills
- cashFlowStatement
- chartOfAccounts
- company
- creditNotes
- customers
- directCosts
- directIncomes
- invoices
- itemReceipts
- items
- journalEntries
- journals
- paymentMethods
- payments
- profitAndLoss
- purchaseOrders
- salesOrders
- suppliers
- taxRates
- trackingCategories
- transfers
- banking-accountBalances
- banking-accounts
- banking-transactionCategories
- banking-transactions
- commerce-companyInfo
- commerce-customers
- commerce-disputes
- commerce-locations
- commerce-orders
- commerce-paymentMethods
- commerce-payments
- commerce-productCategories
- commerce-products
- commerce-taxComponents
- commerce-transactions
example: invoices
DateTime:
title: Date time
type: string
examples:
- 2022-10-23T00:00:00.000Z
- 2022-10-23T00:00:00.000Z
description: |-
In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example:
```
2020-10-08T22:40:50Z
2021-01-01T00:00:00
```
When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:
- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`
- Unqualified local time: `2021-11-15T01:00:00`
- UTC time offsets: `2021-11-15T01:00:00-05:00`
> Time zones
>
> Not all dates from Codat will contain information about time zones.
> 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.
PullOperation:
title: Pull operation
description: |-
Information about a queued, in progress or completed pull operation.
*Formally called `dataset`*
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the pull operation.
example: 943accd0-4247-42d8-865b-363c8629e1da
companyId:
type: string
format: uuid
description: Unique identifier of the company associated to this pull operation.
example: 22ece347-e5f6-4896-95e0-35a4c7f17023
connectionId:
type: string
format: uuid
description: Unique identifier of the connection associated to this pull operation.
example: 50830828-7d39-4367-b0eb-5ddb2de5faa5
dataType:
title: Data types
x-internal: true
type: string
description: The data type you are requesting in a pull operation.
status:
title: Dataset status
type: string
description: The current status of the dataset.
enum:
- Initial
- Queued
- Fetching
- MapQueued
- Mapping
- Complete
- FetchError
- MapError
- InternalError
- ProcessingQueued
- Processing
- ProcessingError
- ValidationQueued
- Validating
- ValidationError
- AuthError
- Cancelled
- NotSupported
- RateLimitError
- PermissionsError
- PrerequisiteNotMet
statusDescription:
type: string
nullable: true
description: Additional information about the dataset status.
example: 'Paused until 2022-10-23T00:00:00.000Z'
errorMessage:
type: string
nullable: true
description: A message about a transient or persistent error returned by Codat or the source platform.
requested:
$ref: '#/components/schemas/DateTime'
completed:
$ref: '#/components/schemas/DateTime'
progress:
type: integer
description: An integer signifying the progress of the pull operation.
isCompleted:
type: boolean
description: '`True` if the pull operation is completed successfully. The `isCompleted` property is not queryable. To filter failed pull operations, query by `status!=Complete&&status!=NotSupported` instead.'
isErrored:
type: boolean
description: '`True` if the pull operation entered an error state.'
required:
- id
- companyId
- connectionId
- dataType
- status
- requested
- progress
- isCompleted
- isErrored
examples:
- id: 97d60846-f07a-4d42-b5a0-0bdcc6ebf56b
companyId: 4645bd78-8988-45bc-ac9e-67ba5df6e4e5
connectionId: 51baa045-4836-4317-a42e-3542e991e581
dataType: invoices
status: Initial
statusDescription: 'Paused until 2022-10-23T00:00:00.000Z'
requested: '2022-11-14T11:18:37.2798351Z'
progress: 10
isCompleted: false
isErrored: false
PullOperations:
title: Pull operations
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/PullOperation'
- $ref: '#/components/schemas/Companies/allOf/1'
PushOperation:
title: Push operation
type: object
x-internal: true
properties:
changes:
type: array
nullable: true
description: 'Contains a single entry that communicates which record has changed and the manner in which it changed. '
items:
$ref: '#/components/schemas/PushOperation/definitions/pushOperationChange'
dataType:
$ref: '#/components/schemas/DataType'
description: 'The type of data being pushed, eg invoices, customers.'
companyId:
$ref: '#/components/parameters/companyId/schema'
pushOperationKey:
type: string
format: uuid
description: 'A unique identifier generated by Codat to represent this single push operation. This identifier can be used to track the status of the push, and should be persisted.'
dataConnectionKey:
$ref: '#/components/parameters/connectionId/schema'
requestedOnUtc:
$ref: '#/components/schemas/DateTime'
description: The datetime when the push was requested.
completedOnUtc:
$ref: '#/components/schemas/DateTime'
description: 'The datetime when the push was completed, null if Pending.'
timeoutInMinutes:
type: integer
format: int32
nullable: true
description: Number of minutes the push operation must complete within before it times out.
timeoutInSeconds:
type: integer
format: int32
nullable: true
deprecated: true
description: Number of seconds the push operation must complete within before it times out.
status:
$ref: '#/components/schemas/PushOperation/definitions/pushOperationStatus'
errorMessage:
type: string
nullable: true
description: A message about the error.
validation:
$ref: '#/components/schemas/PushOperation/definitions/validation'
statusCode:
type: integer
description: Push status code.
required:
- companyId
- pushOperationKey
- dataConnectionKey
- requestedOnUtc
- status
- statusCode
definitions:
validation:
type: object
title: Validation
description: 'A human-readable object describing validation decisions Codat has made when pushing data into the platform. If a push has failed because of validation errors, they will be detailed here.'
properties:
errors:
type: array
nullable: true
items:
$ref: '#/components/schemas/PushOperation/definitions/validationItem'
warnings:
type: array
nullable: true
items:
$ref: '#/components/schemas/PushOperation/definitions/validationItem'
validationItem:
title: Validation 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.
additionalProperties: false
pushChangeType:
title: Push change type
description: Type of change being applied to record in third party platform.
type: string
enum:
- Unknown
- Created
- Modified
- Deleted
- AttachmentUploaded
pushOperationRef:
title: Push operation reference
x-internal: true
type: object
properties:
id:
type: string
description: Unique identifier for a push operation.
dataType:
$ref: '#/components/schemas/DataType'
nullable: true
additionalProperties: false
pushOperationStatus:
title: Push operation status
type: string
enum:
- Pending
- Failed
- Success
- TimedOut
description: The current status of the push operation.
pushOperationChange:
type: object
properties:
type:
$ref: '#/components/schemas/PushOperation/definitions/pushChangeType'
recordRef:
$ref: '#/components/schemas/PushOperation/definitions/pushOperationRef'
attachmentId:
type: string
description: Unique identifier for the attachment created otherwise null.
nullable: true
PushOperations:
title: Push operations
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/PushOperation'
- $ref: '#/components/schemas/Companies/allOf/1'
PushOption:
title: Push option
x-internal: true
required:
- displayName
- required
- type
type: object
properties:
type:
$ref: '#/components/schemas/PushOption/definitions/pushOptionType'
displayName:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/displayName'
description:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/description'
required:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/required'
properties:
type: object
additionalProperties:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty'
nullable: true
options:
type: array
items:
$ref: '#/components/schemas/PushOption/definitions/pushOptionChoice'
nullable: true
validation:
$ref: '#/components/schemas/PushOption/definitions/pushValidationInfo'
nullable: true
definitions:
pushOptionProperty:
title: Push Option Property
required:
- description
- displayName
- required
- type
type: object
properties:
type:
$ref: '#/components/schemas/PushOption/definitions/pushOptionType'
displayName:
minLength: 1
type: string
description: The property's display name.
description:
type: string
description: A description of the property.
required:
type: boolean
description: The property is required if `True`.
properties:
type: object
additionalProperties:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty'
nullable: true
options:
type: array
items:
$ref: '#/components/schemas/PushOption/definitions/pushOptionChoice'
nullable: true
validation:
$ref: '#/components/schemas/PushOption/definitions/pushValidationInfo'
pushValidationInfo:
title: Push validation info
type: object
properties:
warnings:
type: array
items:
$ref: '#/components/schemas/PushOption/definitions/pushFieldValidation'
nullable: true
information:
type: array
items:
$ref: '#/components/schemas/PushOption/definitions/pushFieldValidation'
nullable: true
additionalProperties: false
pushFieldValidation:
title: Push field validation
required:
- details
type: object
properties:
field:
type: string
description: Field name that resulted in the validation issue.
details:
minLength: 1
type: string
description: Details on the validation issue.
ref:
type: string
format: uri
nullable: true
description: Unique reference identifier for the validation issue.
additionalProperties: false
pushOptionType:
title: Option Type
description: The option type.
enum:
- Array
- Object
- String
- Number
- Boolean
- DateTime
- File
- MultiPart
type: string
pushOptionChoice:
title: Push Option Choice
type: object
properties:
value:
type: string
minLength: 1
description: Allowed value for field.
type:
$ref: '#/components/schemas/PushOption/definitions/pushOptionType'
displayName:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/displayName'
description:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/description'
required:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/required'
SourceAccount:
title: Source account (v1)
type: object
description: The target bank account in a supported accounting software for ingestion into a bank feed.
additionalProperties: false
properties:
id:
type: string
description: Unique ID for the bank account.
accountName:
type: string
nullable: true
description: The bank account name.
accountType:
type: string
nullable: true
description: The type of bank account e.g. Credit.
accountNumber:
type: string
nullable: true
description: The account number.
sortCode:
type: string
nullable: true
description: The sort code.
currency:
title: Currency
x-internal: true
type: string
description: |-
The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, e.g. _GBP_.
## Unknown currencies
In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction.
There are only a very small number of edge cases where this currency code is returned by the Codat system.
format: ISO4217
examples:
- GBP
- USD
- EUR
balance:
type: number
format: decimal
nullable: true
description: The latest balance for the bank account.
modifiedDate:
$ref: '#/components/schemas/DateTime'
nullable: true
description: The last date the bank account was modified.
status:
type: string
nullable: true
description: Status of the source account.
enum:
- pending
- connected
- connecting
- disconnected
- unknown
feedStartDate:
$ref: '#/components/schemas/DateTime'
nullable: true
required:
- id
definitions:
sourceAccounts:
title: Source accounts
type: array
items:
$ref: '#/components/schemas/SourceAccount'
examples:
- id: acc-002
accountName: account-081
sortCode: '123456'
accountType: Credit
accountNumber: '12345670'
currency: GBP
balance: 99.99
modifiedDate: '2023-01-09T14:14:14.1057478Z'
status: pending
- id: acc-003
accountName: account-095
sortCode: '123456'
accountType: Credit
accountNumber: '12345671'
currency: USD
balance: 0
modifiedDate: '2023-01-09T14:14:14.1057478Z'
status: pending
SourceAccountV2:
title: Source account (v2)
type: object
description: The target bank account in a supported accounting software for ingestion into a bank feed.
additionalProperties: false
properties:
id:
type: string
description: Unique ID for the bank account.
accountName:
type: string
description: The bank account name.
accountType:
type: string
description: 'The type of bank account e.g. checking, savings, loan, creditCard, prepaidCard.'
enum:
- checking
- savings
- loan
- creditCard
- prepaidCard
accountNumber:
type: string
description: The account number.
routingInfo:
$ref: '#/components/schemas/SourceAccountV2/definitions/routingInfo'
currency:
$ref: '#/components/schemas/SourceAccount/properties/currency'
balance:
type: number
format: decimal
description: The latest balance for the bank account.
accountInfo:
$ref: '#/components/schemas/SourceAccountV2/definitions/accountInfo'
modifiedDate:
$ref: '#/components/schemas/DateTime'
nullable: true
description: The last date the bank account was modified.
status:
type: string
nullable: true
description: Status of the source account.
enum:
- pending
- connected
- connecting
- disconnected
- unknown
feedStartDate:
nullable: true
title: Date
type: string
example: '2022-10-23'
description: |-
In Codat's data model, dates are represented using the ISO 8601 standard. Date fields are formatted as strings; for example:
```
2020-10-08
```
required:
- id
- accountName
- accountType
- accountNumber
- currency
- balance
definitions:
accountInfo:
title: Account Info
type: object
nullable: true
properties:
description:
type: string
nullable: true
description: Description of the account.
nickname:
type: string
nullable: true
description: Name given to the account by the user. Used in UIs to assist in account selection.
accountOpenDate:
$ref: '#/components/schemas/SourceAccountV2/properties/feedStartDate'
nullable: true
description: Date when the account was opened or created at the provider
availableBalance:
type: number
format: decimal
nullable: true
description: Balance of funds available for use. This includes pending activity.
sourceAccounts:
title: Source accounts
type: array
items:
$ref: '#/components/schemas/SourceAccountV2'
routingInfo:
title: Routing Info
type: object
description: Routing information for the bank. This does not include account number.
properties:
bankCode:
type: string
nullable: true
description: The numeric identifier of the routing number
type:
type: string
nullable: true
default: bankcode
enum:
- rtn
- aba
- swift
- bsb
- iban
- nz2
- trno
- sortcode
- blz
- ifsc
- bankcode
- apca
- clabe
description: The type of routing number.
examples:
- id: acc-001
accountName: account-081
accountType: checking
accountNumber: '12345670'
routingInfo:
bankCode: 021001088
type: bankcode
currency: GBP
balance: 99.99
accountInfo:
description: account description 1
nickname: account 123
accountOpenDate: 2023-05-06T00:00:00.000Z
availableBalance: 10
modifiedDate: '2024-08-02T00:00:00.000Z'
status: pending
feedStartDate: 2024-05-01T00:00:00.000Z
- id: acc-002
accountName: account-083
accountType: savings
accountNumber: '23456789'
routingInfo:
bankCode: 021001088
type: bankcode
currency: GBP
balance: 400
accountInfo:
description: account description 2
nickname: account 1290
accountOpenDate: 2023-05-23T00:00:00.000Z
availableBalance: 400
modifiedDate: '2024-08-02T00:00:00.000Z'
status: pending
feedStartDate: 2024-05-01T00:00:00.000Z
SourceAccountWebhook:
title: Source account status changed webhook
type: object
properties:
id:
type: string
format: uuid
example: ba29118f-5406-4e59-b05c-ba307ca38d01
description: Unique identifier of the event.
eventType:
type: string
description: The type of event.
examples:
- bankFeeds.sourceAccount.connected
- bankFeeds.sourceAccount.disconnected
generatedDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC the event was generated in Codat.
payload:
$ref: '#/components/schemas/SourceAccountWebhook/definitions/sourceAccountWebhookPayload'
definitions:
sourceAccountWebhookPayload:
title: Payload
type: object
properties:
referenceCompany:
$ref: '#/components/schemas/Company/definitions/companyReference'
companyId:
$ref: '#/components/parameters/companyId/schema'
deprecated: true
connectionId:
$ref: '#/components/parameters/connectionId/schema'
sourceAccount:
$ref: '#/components/schemas/SourceAccount'
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.
connectionId:
name: connectionId
in: path
required: true
schema:
type: string
format: uuid
example: 2e9d2c44-f675-40ba-8049-353bfcb5e171
description: Unique identifier for a company's data connection.
description: Unique identifier for a connection.
accountId:
name: accountId
in: path
required: true
schema:
type: string
examples:
- 13d946f0-c5d5-42bc-b092-97ece17923ab
- 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2
- 7110701885
- EILBDVJVNUAGVKRQ
description: Unique identifier for an account.
page:
name: page
in: query
schema:
type: integer
format: int32
minimum: 1
example: 1
default: 1
description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).'
pageSize:
name: pageSize
in: query
schema:
type: integer
format: int32
default: 100
example: 100
minimum: 1
maximum: 5000
description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).'
query:
name: query
in: query
required: false
schema:
type: string
example: id=e3334455-1aed-4e71-ab43-6bccf12092ee
description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).'
orderBy:
name: orderBy
in: query
required: false
schema:
type: string
example: '-modifiedDate'
description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).'
dataType:
name: dataType
description: The key of a Codat data type
in: path
required: true
schema:
$ref: '#/components/schemas/DataType'
datasetId:
name: datasetId
in: path
required: true
schema:
type: string
format: uuid
description: Unique identifier for the dataset that completed its sync.
description: Unique identifier for the dataset that completed its sync.
timeoutInMinutes:
name: timeoutInMinutes
in: query
schema:
type: integer
format: int32
description: Time limit for the push operation to complete before it is timed out.
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
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
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
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
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
Conflict:
description: The data type's dataset has not been requested or is still syncing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Conflict:
value:
statusCode: 409
service: PublicApi
error: The data set has not been requested.
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
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
securitySchemes:
auth_header:
name: Authorization
description: 'The word "Basic" followed by a space and your API key. [API keys](https://docs.codat.io/bank-feeds-api#/schemas/apiKeys) 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/codat-api#/api-keys/api-keys-list), 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)