openapi: 3.1.0
servers:
- description: Production
url: 'https://api.codat.io'
info:
title: Bill pay kit
description: |-
The API reference for the Bill Pay kit.
The bill pay kit is an API and a set of supporting tools designed to integrate a bill pay flow into your app as quickly as possible. It's ideal for facilitating essential bill payment processes within your SMB's accounting software.
[Explore product](https://docs.codat.io/payables/bill-pay-kit) | [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. |
| Company information | View company profile from the source platform. |
| Bills | Get, create, and update Bills. |
| Bill payments | Get, create, and update Bill payments. |
| Suppliers | Get, create, and update Suppliers. |
| Bank accounts | Create a bank account for a given company's connection. |
version: 3.0.0
contact:
name: Codat
email: support@codat.io
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: sync-for-payables-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: Company information
description: View company profile from the source platform.
- name: Bills
description: 'Get, create, and update Bills.'
- name: Bill payments
description: 'Get, create, and update Bill payments.'
- name: Suppliers
description: 'Get, create, and update Suppliers.'
- name: Bank accounts
description: Create a bank account for a given company's connection.
paths:
/companies:
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/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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'
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/sync-for-payables-api#/schemas/Company) that represents your customer in Codat. \n\nA [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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'
'/companies/{companyId}':
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/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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
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/sync-for-payables-api#/schemas/Company), its [connections](https://docs.codat.io/sync-for-payables-api#/schemas/Connection) and any cached data. This operation is irreversible.\n\nA [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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'
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/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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'
'/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/sync-for-payables-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}/connections/{connectionId}/payables/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:
Company information:
value:
companyName: Bank of Dave
baseCurrency: GBP
'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}/payables/mappingOptions/bills':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get bill mapping options
description: "\uFEFFUse the *Get mapping options - Bills* endpoint to return a list of available mapping options for a given company's connection ID.\n\nBy default, this endpoint returns a list of active accounts and tax rates. You can use [querying](https://docs.codat.io/using-the-api/querying) to change that.\n\nMapping options are a set of accounts and tax rates used to configure the SMB's payables integration."
operationId: get-mapping-options-bills
x-speakeasy-name-override: get-bill-options
tags:
- Bills
parameters:
- $ref: '#/components/parameters/continuationToken'
- $ref: '#/components/parameters/statusQuery'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BillMappingOptions'
examples:
Mapping options:
value:
accounts:
- id: 1b6266d1-1e44-46c5-8eb5-a8f98e03124e
nominalCode: 879-i
name: Accounts payable
type: Liability
currency: GBP
status: Active
sourceModifiedDate: 2022-10-23T00:00:00.000Z
taxRates:
- id: d2939064-dd3a-4c0f-9865-a238c2193515
name: VAT @ 20%
code: VAT20
effectiveTaxRate: 20
totalTaxRate: 20
status: Active
sourceModifiedDate: 2022-10-23T00:00:00.000Z
pagination:
continuationToken: eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==
'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}/payables/mappingOptions/payments':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get payment mapping options
description: "Use the *Get mapping options - Payments* endpoint to return a list of available mapping options for a given company's connection ID.\r\n\r\nBy default, this endpoint returns a list of active bank accounts. You can use [querying](https://docs.codat.io/using-the-api/querying) to change that.\r\n\r\nMapping options are a set of bank accounts used to configure the SMB's payables integration."
operationId: get-mapping-options-payments
x-speakeasy-name-override: get-payment-options
tags:
- Bill payments
parameters:
- $ref: '#/components/parameters/continuationToken'
- $ref: '#/components/parameters/statusQuery'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMappingOptions'
examples:
Mapping options:
value:
bankAccounts:
- id: 3d5a8e00-d108-4045-8823-7f342676cffa
name: Bank of Dave current account
accountNumber: '12345678'
currency: GBP
nominalCode: '1234567'
sortCode: '123456'
status: Active
accountType: Debit
sourceModifiedDate: 2022-10-23T00:00:00.000Z
pagination:
continuationToken: eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==
'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}/payables/bills':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List bills
description: |-
The *List bills* endpoint returns a list of [bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) for a given company's connection.
[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services.
By default, the endpoint will return all bills with a status of 'Open' & 'PartiallyPaid' to show all oustanding bills.
operationId: list-bills
tags:
- Bills
parameters:
- $ref: '#/components/parameters/continuationToken'
- name: query
in: query
required: false
schema:
type: string
examples:
Status (open):
value: status=Open
Status (partially paid):
value: status=PartiallyPaid
Source modified date:
value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z'
Status (open) & source modified date:
value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Open'
Status (partially paid) & source modified date:
value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=PartiallyPaid'
description: 'Codat query string allows you to filter by `status` and `sourceModifiedDate`. Learn more about Codat''s query string [here](https://docs.codat.io/using-the-api/querying). Platfrom specfic statuses: Xero supports Open | PartiallyPaid | Paid | Void | Draft. Qbo supports Open | PartiallyPaid | Paid. FreeAgent supports Open | PartiallyPaid | Paid.'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Bill/definitions/bills'
examples:
Bills:
value:
results:
- id: '18'
reference: '12'
supplierRef:
id: '4'
supplierName: BILLy elliot
issueDate: '2019-05-13T00:00:00'
dueDate: '2019-05-13T00:00:00'
currency: GBP
currencyRate: '1,'
lineItems:
- description: Dance shoes
unitAmount: 5
quantity: 1
taxAmount: 0
accountRef:
id: '16'
taxRateRef:
id: NON
totalAmount: 5
status: Open
totalAmount: 5
amountDue: 0
sourceModifiedDate: '2022-05-26T10:34:10Z'
- id: '22'
reference: '12'
supplierRef:
id: '4'
supplierName: BILLy elliot
issueDate: '2019-05-13T00:00:00'
dueDate: '2019-05-13T00:00:00'
currency: GBP
currencyRate: 1
lineItems:
- description: Dance shoes
unitAmount: 5
quantity: 1
taxAmount: 0
accountRef:
id: '16'
taxRateRef:
id: NON
totalAmount: 5
status: Paid
totalAmount: 5
amountDue: 0
sourceModifiedDate: '2022-05-26T10:34:10Z'
pagination:
continuationToken: eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==
'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'
post:
summary: Create bill
description: |-
The *Create bill* endpoint creates a new [bill](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) for a given company's connection.
[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services.
operationId: create-bill
tags:
- Bills
parameters:
- in: header
name: Idempotency-Key
description: A unique identifier to ensure idempotent behaviour for subsequent requests.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Bill/definitions/billPrototype'
examples:
Create bill:
value:
reference: bill_b8qmmj4ksf1suax
supplierRef:
id: 1262c350-fe0f-40ec-aeff-41c95b4a45af
supplierName: DIISR - Small Business Services
issueDate: '2023-04-23T00:00:00'
dueDate: '2023-04-23T00:00:00'
currency: GBP
currencyRate: 1
lineItems:
- description: Half day training - Microsoft Office
unitAmount: 1800
quantity: 1
taxAmount: 360
totalAmount: 2160
accountRef:
id: 46f9461e-788b-4906-8b74-d1ea17f6dc10
taxRateRef:
id: INPUT2
- description: Desktop/network support via email & phone.Per month fixed fee for minimum 20 hours/month.
unitAmount: 4000
quantity: 1
taxAmount: 800
totalAmount: 4800
accountRef:
id: f96c9458-d724-47bf-8f74-a9d5726465ce
taxRateRef:
id: INPUT2
- description: Stationery charges
unitAmount: 32
quantity: 8
taxAmount: 51.2
totalAmount: 307.2
accountRef:
id: cba6527d-f102-4538-b421-e483233e9d5a
taxRateRef:
id: INPUT2
status: Open
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Bill'
examples:
Created bill:
value:
id: bill-1029932
reference: bill_b8qmmj4ksf1suax
supplierRef:
id: 1262c350-fe0f-40ec-aeff-41c95b4a45af
supplierName: DIISR - Small Business Services
issueDate: '2023-04-23T00:00:00'
dueDate: '2023-04-23T00:00:00'
currency: GBP
lineItems:
- description: Half day training - Microsoft Office
unitAmount: 1800
quantity: 1
taxAmount: 360
totalAmount: 2160
accountRef:
id: 46f9461e-788b-4906-8b74-d1ea17f6dc10
taxRateRef:
id: INPUT2
- description: Desktop/network support via email & phone.Per month fixed fee for minimum 20 hours/month.
unitAmount: 4000
quantity: 1
taxAmount: 800
totalAmount: 4800
accountRef:
id: f96c9458-d724-47bf-8f74-a9d5726465ce
taxRateRef:
id: INPUT2
- description: Stationery charges
unitAmount: 32
quantity: 8
taxAmount: 51.2
totalAmount: 307.2
accountRef:
id: cba6527d-f102-4538-b421-e483233e9d5a
taxRateRef:
id: INPUT2
status: Open
totalAmount: 7267.2
amountDue: 7267.2
'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'
'409':
$ref: '#/components/responses/Idempotency-Conflict'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'/companies/{companyId}/connections/{connectionId}/payables/bills/{billId}/attachments':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/billId'
post:
summary: Upload bill attachment
description: "The *Upload bill attachment* endpoint uploads an attachment and assigns it against a specific `billId`.\r\n\r\n[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services."
operationId: upload-bill-attachment
tags:
- Bills
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/AttachmentUpload'
responses:
'201':
description: Created
'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}/bills/{billId}/attachments':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/billId'
get:
tags:
- Bills
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Attachment'
examples:
Info:
value:
id: 422f093f-e556-4bf3-91c0-93af70c3e850
name: receipt.png
contentType: image/png
dateCreated: '2022-10-23T00:00:00.000Z'
fileSize: 100
includeWhenSent: true
sourceModifiedDate: '2022-05-26T10:34:10Z'
'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'
operationId: list-bill-attachments
summary: List bill attachments
description: "The *List bill attachments* endpoint returns a list of attachments available to download for a given `billId`.\r\n\r\n[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services."
'/companies/{companyId}/connections/{connectionId}/payables/bills/{billId}/attachments/{attachmentId}/download':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/billId'
- $ref: '#/components/parameters/attachmentId'
get:
summary: Download bill attachment
description: |
The *Download bill attachment* endpoint downloads a specific attachment for a given `billId` and `attachmentId`.
[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services.
Check out our [coverage explorer](https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=bills) for integrations that support downloading a bill attachment.
operationId: download-bill-attachment
tags:
- Bills
responses:
'200':
description: Success
content:
application/octet-stream:
schema:
title: Data
type: string
format: binary
'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}/payables/bills/{billId}/payment':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/billId'
- in: header
name: Idempotency-Key
description: A unique identifier to ensure idempotent behaviour for subsequent requests.
schema:
type: string
post:
summary: Create bill payment
description: |-
The *Create bill payment* endpoint creates a new [bill payment](https://docs.codat.io/sync-for-payables-api#/schemas/BillPayment) for a given company's connection.
[Bill payments](https://docs.codat.io/sync-for-payables-api#/schemas/BillPayment) are an allocation of money within any Accounts Payable account.
operationId: create-bill-payment
tags:
- Bill payments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BillPayment/definitions/billPaymentPrototype'
examples:
Bill payment example:
value:
amount: 22
currencyRate: 1
date: '2022-10-23T00:00:00.000Z'
accountRef:
id: 7bda9f44sr56
reference: Bill Payment against bill c13e37b6 dfaa-4894-b3be-9fe97bda9f44
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/BillPayment'
examples:
Bill payment:
value:
id: billPayment-1029932
amount: 22
currencyRate: 1
date: '2022-10-23T00:00:00.000Z'
accountRef:
id: 7bda9f44sr56
reference: Bill Payment against bill c13e37b6 dfaa-4894-b3be-9fe97bda9f44
'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'
'409':
$ref: '#/components/responses/Idempotency-Conflict'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'/companies/{companyId}/connections/{connectionId}/payables/suppliers':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
tags:
- Suppliers
summary: List suppliers
description: |-
The *List suppliers* endpoint returns a list of [suppliers](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) for a given company's connection.
[Suppliers](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) are people or organizations that provide something, such as a product or service.
By default, this endpoint returns a list of active and archived suppliers. You can use [querying](https://docs.codat.io/using-the-api/querying) to change that.
For example, to retrieve only active suppliers (i.e. `status=Active`) or suppliers created within the specified number of days (e.g. `sourceModifiedDate>2023-12-15T00:00:00.000Z`), query the endpoint as follows: `/payables/suppliers?query=sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Active`.For example, to retrieve active suppliers modified after a particular date use `query=sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Active`.
operationId: list-suppliers
parameters:
- $ref: '#/components/parameters/continuationToken'
- name: query
in: query
required: false
schema:
type: string
examples:
Source modified date:
value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z'
Status (active):
value: status=Active
Status (archived):
value: status=Archived
Status (active) & source modified date:
value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Active'
Status (archived) & source modified date:
value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Archived'
description: 'Codat query string allows you to filter by `sourceModifiedDate` or if a supplier is `Active` or `Archived` in the accounting software. Learn more about Codat''s query string [here](https://docs.codat.io/using-the-api/querying).'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Supplier/definitions/suppliers'
examples:
Suppliers:
value:
results:
- id: c523e12f-8b74-4d3a-bbd8-32d7a2f598b4
supplierName: City Limousines
contactName: Martin Dale
emailAddress: martyd@citylim.co
phone: 07999 999999
addresses:
- type: Billing
line1: Unit 51
line2: Bakersfield Industrial Estate
city: Bakersfield
region: California
country: USA
postalcode: '93308'
status: Active
balance: 100
defaultCurrency: GBP
sourceModifiedDate: '2022-10-23T00:00:00Z'
- id: '41'
supplierName: AI Support
contactName: AI Support
addresses:
- type: Billing
line1: test
region: string
country: Djibouti
status: Active
defaultCurrency: GBP
sourceModifiedDate: '2022-12-07T10:48:18Z'
pagination:
continuationToken: eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==
'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'
post:
tags:
- Suppliers
summary: Create supplier
description: "The *Create supplier* endpoint creates a new [supplier](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) for a given company's connection.\r\n\r\n[Suppliers](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) are people or organizations that provide something, such as a product or service.\r\n"
operationId: create-supplier
parameters:
- in: header
name: Idempotency-Key
description: A unique identifier to ensure idempotent behaviour for subsequent requests.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Supplier/definitions/supplierPrototype'
examples:
Suppliers:
value:
supplierName: Greggs
contactName: Greg Greggs
emailAddress: greg@greggs.com
phone: +44 (0)1223 322410
addresses:
- type: Billing
line1: Flat 1
line2: 2 Dennis Avenue
city: London
region: Camden
country: GBR
postalCode: EC1N 7TE
status: Active
defaultCurrency: GBP
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Supplier'
examples:
Suppliers:
value:
id: sup-10933920
supplierName: Greggs
contactName: Greg Greggs
emailAddress: greg@greggs.com
phone: +44 (0)1223 322410
address:
- type: Billing
line1: Flat 1
line2: 2 Dennis Avenue
city: London
region: Camden
country: GBR
postalCode: EC1N 7TE
status: Active
defaultCurrency: GBP
'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}/payables/bankAccounts':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
post:
tags:
- Bank accounts
summary: Create bank account
parameters:
- in: header
name: Idempotency-Key
description: A unique identifier to ensure idempotent behaviour for subsequent requests.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount/definitions/bankAccountPrototype'
examples:
Bank account example:
value:
id: fb623ab2-f6ff-4b22-b7d3-b7cc2a4aa0ea
nominalCode: '22'
name: Plutus - Payables - Bank Account 12
accountNumber: 0120 0440
sortCode: 50-50-50
currency: GBP
accountType: Debit
status: Active
sourceModifiedDate: 2024-02-22T14:46:43.990Z
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount'
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/sync-for-payables-api#/schemas/BankAccount) for a given company's connection.\r\n\r\n[Bank accounts](https://docs.codat.io/sync-for-payables-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution."
operationId: create-bank-account
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.
components:
schemas:
Address:
title: Address
x-internal: true
type: object
properties:
type:
$ref: '#/components/schemas/Address/definitions/addressType'
line1:
type: string
nullable: true
description: Line 1 of the customer address.
line2:
type: string
nullable: true
description: Line 2 of the customer address.
city:
type: string
nullable: true
description: City of the customer address.
region:
type: string
nullable: true
description: Region of the customer address.
country:
type: string
nullable: true
description: 'Country of the customer''s address. For NetSuite, use the 2-digit [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code.'
postalCode:
type: string
nullable: true
description: Postal code or zip code.
definitions:
addressType:
description: The type of the address
type: string
enum:
- Unknown
- Billing
- Delivery
Attachment:
title: Attachment
description: |2-
The Codat API supports pulling and pushing of file attachments for invoices, bills, direct costs, and direct incomes.
> **Retrieving attachments**
>
> If a company is authorized, you can query the Codat API to read, download, and upload attachments without requiring a fresh sync of data.
Unlike other data types, Codat doesn't support [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings) for attachments.
Note that different integrations have different requirements for file size and extension of attachments.
| Integration | File size | File extension |
|-------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Xero | 4 MB | 7Z, BMP, CSV, DOC, DOCX, EML, GIF, JPEG, JPG, KEYNOTE, MSG, NUMBERS, ODF, ODS, ODT, PAGES, PDF, PNG, PPT, PPTX, RAR, RTF, TIF, TIFF, TXT, XLS, XLSX, ZIP |
| QuickBooks Online | 100 MB | AI, CSV, DOC, DOCX, EPS, GIF, JPEG, JPG, ODS, PAGES, PDF, PNG, RTF, TIF, TXT, XLS, XLSX, XML |
| NetSuite | 100 MB | BMP, CSV, XLS, XLSX, JSON, PDF, PJPG, PJPEG, PNG, TXT, SVG, TIF, TIFF, DOC, DOCX, ZIP |
| Dynamics 365 Business Central | 350 MB | Dynamics do not explicitly outline which file types are supported but they do state here that "You can attach any type of file, such as text, image, or video files". |
type: object
allOf:
- type: object
properties:
id:
type: string
description: 'Identifier for the attachment, unique for the company in the accounting software.'
name:
type: string
nullable: true
description: Name of the attachment file.
contentType:
type: string
nullable: true
description: |-
File type of the attachment. This is represented by appending the file type to the [IETF standard file naming requirements](https://tools.ietf.org/html/rfc6838). For example, for a jpeg file the output is **image/jpeg**.
Supported file types vary per platform.
dateCreated:
$ref: '#/components/schemas/Connection/properties/created'
fileSize:
type: integer
format: int32
nullable: true
description: 'File size in bytes. For example, if this reads **46153**, then the file size is 46kb.'
includeWhenSent:
type: boolean
description: 'If `true`, then the attachment is included with the associated invoice, bill or direct costs when it is printed, emailed, or sent to a customer, if the underlying accounting software allows this.'
- title: Source Modified Date
x-internal: true
type: object
nullable: true
properties:
sourceModifiedDate:
allOf:
- $ref: '#/components/schemas/Connection/properties/created'
- 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.
AttachmentUpload:
title: Attachment upload
type: object
x-internal: true
required:
- file
properties:
file:
$ref: '#/components/schemas/AttachmentUpload/definitions/codatFile'
definitions:
codatFile:
type: string
description: The file to be uploaded as an attachment.
format: binary
BankAccount:
title: Bank accounts
type: object
allOf:
- properties:
id:
type: string
description: 'Identifier for the bank account, unique for the company in the accounting software.'
nominalCode:
type: string
nullable: true
description: Code used to identify each nominal account for a business.
name:
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.
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.
sortCode:
type: string
nullable: true
description: |-
Sort code for the bank account. This is relevant to UK bank accounts.
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.
currency:
$ref: '#/components/schemas/Bill/properties/currency'
description: Base currency of the bank account.
status:
$ref: '#/components/schemas/BankAccount/definitions/bankAccountStatus'
- $ref: '#/components/schemas/Attachment/allOf/1'
definitions:
bankAccountStatus:
type: string
description: The current status of the bank account.
enum:
- Active
- Archived
bankAccountPrototype:
title: Bank account prototype
type: object
properties:
nominalCode:
$ref: '#/components/schemas/BankAccount/allOf/0/properties/nominalCode'
name:
$ref: '#/components/schemas/BankAccount/allOf/0/properties/name'
accountType:
$ref: '#/components/schemas/BankAccount/allOf/0/properties/accountType'
accountNumber:
$ref: '#/components/schemas/BankAccount/allOf/0/properties/accountNumber'
sortCode:
$ref: '#/components/schemas/BankAccount/allOf/0/properties/sortCode'
currency:
$ref: '#/components/schemas/BankAccount/allOf/0/properties/currency'
required:
- name
- accountType
- accountNumber
- currency
Bill:
title: Bill
description: "\uFEFFBills are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services."
type: object
properties:
id:
type: string
description: 'Identifier for the bill, unique for the company in the accounting software.'
reference:
type: string
nullable: true
description: User-friendly reference for the bill.
supplierRef:
$ref: '#/components/schemas/Supplier/definitions/supplierRef'
issueDate:
allOf:
- description: Date of the bill as recorded in the accounting software.
- $ref: '#/components/schemas/Connection/properties/created'
dueDate:
allOf:
- description: Date the supplier is due to be paid.
- $ref: '#/components/schemas/Connection/properties/created'
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
currencyRate:
title: Currency rate
type: number
format: decimal
nullable: true
description: |-
Rate to convert the total amount of the payment into the base currency for the company at the time of the payment.
Currency rates in Codat are implemented as the multiple of foreign currency units to each base currency unit.
It is not possible to perform the currency conversion with two or more non-base currencies participating in the transaction. For example, if a company's base currency is USD, and it has a bill issued in EUR, then the bill payment must happen in USD or EUR.
Where the currency rate is provided by the underlying accounting software, it will be available from Codat with the same precision (up to a maximum of 9 decimal places).
For accounting software which do not provide an explicit currency rate, it is calculated as `baseCurrency / foreignCurrency` and will be returned to 9 decimal places.
## Examples with base currency of GBP
| Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (GBP) |
| :--------------- | :------------- | :------------ | :------------------------- |
| **USD** | $20 | 0.781 | £15.62 |
| **EUR** | €20 | 0.885 | £17.70 |
| **RUB** | ₽20 | 0.011 | £0.22 |
## Examples with base currency of USD
| Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (USD) |
| :--------------- | :------------- | :------------ | :------------------------- |
| **GBP** | £20 | 1.277 | $25.54 |
| **EUR** | €20 | 1.134 | $22.68 |
| **RUB** | ₽20 | 0.015 | $0.30 |
### Integration-specific details
| Integration | Scenario | System behavior |
|-------------------|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| QuickBooks Online | Transaction currency differs from base currency | If currency rate value is left `null`, a rate of 1 will be used by QBO by default. To override this, specify a currencyRate in the request body. |
lineItems:
type: array
nullable: true
description: Array of Bill line items.
items:
$ref: '#/components/schemas/Bill/definitions/billLineItem'
status:
$ref: '#/components/schemas/Bill/definitions/billStatus'
totalAmount:
type: number
format: decimal
description: 'Amount of the bill, including tax.'
amountDue:
type: number
format: decimal
nullable: true
description: Amount outstanding on the bill.
sourceModifiedDate:
allOf:
- $ref: '#/components/schemas/Connection/properties/created'
- 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.
required:
- supplierRef
- issueDate
- dueDate
- currency
- status
definitions:
billPrototype:
title: Bill prototype
type: object
properties:
reference:
$ref: '#/components/schemas/Bill/properties/reference'
supplierRef:
$ref: '#/components/schemas/Supplier/definitions/supplierRef'
issueDate:
$ref: '#/components/schemas/Bill/properties/issueDate'
dueDate:
$ref: '#/components/schemas/Bill/properties/dueDate'
currency:
$ref: '#/components/schemas/Bill/properties/currency'
currencyRate:
$ref: '#/components/schemas/Bill/properties/currencyRate'
lineItems:
$ref: '#/components/schemas/Bill/properties/lineItems'
status:
$ref: '#/components/schemas/Bill/definitions/billStatus'
required:
- supplierRef
- issueDate
- dueDate
- currency
- status
billStatus:
description: Current state of the bill. If creating a bill the status must be `Open`.
type: string
enum:
- Unknown
- Open
- PartiallyPaid
- Paid
- Void
- Draft
example: Open
billLineItem:
title: Bill line item
type: object
properties:
description:
type: string
nullable: true
description: Friendly name of the goods or services received.
unitAmount:
type: number
format: decimal
description: Unit price of the goods or service.
quantity:
type: number
format: decimal
description: Number of units of goods or services received.
taxAmount:
type: number
format: decimal
description: Amount of tax applied to the line item.
accountRef:
$ref: '#/components/schemas/Bill/definitions/billAccountRef'
totalAmount:
type: number
format: decimal
nullable: true
description: 'Total amount of the line, including tax.'
taxRateRef:
$ref: '#/components/schemas/Bill/definitions/billTaxRateRef'
required:
- quantity
- unitAmount
- taxRateRef
- accountRef
billAccountRef:
title: Account reference
type: object
description: Reference to the account to which the line item is linked.
properties:
id:
type: string
description: '''id'' from the Accounts data type.'
billTaxRateRef:
title: Tax rate reference
type: object
description: Reference to the tax rate to which the line item is linked.
properties:
id:
type: string
description: Unique identifier for the tax rate in the accounting software.
bills:
title: Bills
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Bill'
pagination:
$ref: '#/components/schemas/Pagination'
BillEventWebhook:
x-internal: true
title: Bill event webhook
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the bill event.
type:
type: string
description: Type of webhook event.
example: payables.bill.created
createdDate:
type: string
description: The datetime in UTC of when the webhook event was produced by Codat.
examples:
- 2022-10-23T11:03:35.000Z
payload:
$ref: '#/components/schemas/BillEventWebhook/definitions/billEventPayload'
definitions:
billEventPayload:
title: Bill event payload
type: object
properties:
companyId:
$ref: '#/components/parameters/companyId/schema'
connectionId:
$ref: '#/components/parameters/connectionId/schema'
pushOperationKey:
type: string
format: uuid
example: 2e9d2c44-f675-40ba-8049-353bfcb5e171
description: Unique identifier for the push operation.
bill:
$ref: '#/components/schemas/Bill'
BillMappingOptions:
x-internal: true
title: Mapping options bills
description: The bill mapping options for a company's accounting software.
type: object
properties:
accounts:
type: array
items:
$ref: '#/components/schemas/BillMappingOptions/definitions/accountMappingOption'
taxRate:
type: array
items:
$ref: '#/components/schemas/BillMappingOptions/definitions/taxRateMappingOption'
pagination:
$ref: '#/components/schemas/Pagination'
definitions:
accountMappingOption:
title: Account mapping option
type: object
allOf:
- properties:
id:
type: string
description: 'Identifier for the account, unique for the company.'
example: 1b6266d1-1e44-46c5-8eb5-a8f98e03124e
nominalCode:
type: string
nullable: true
description: Reference given to each nominal account for a business. It ensures money is allocated to the correct account. This code isn't a unique identifier in the Codat system.
example: '610'
name:
type: string
nullable: true
description: Name of the account.
example: Accounts Payable
type:
type: string
nullable: true
description: Type of account.
example: Liability
currency:
$ref: '#/components/schemas/Bill/properties/currency'
status:
$ref: '#/components/schemas/BillMappingOptions/definitions/accountStatus'
- $ref: '#/components/schemas/Attachment/allOf/1'
taxRateMappingOption:
title: Tax rate mapping option
type: object
allOf:
- properties:
id:
type: string
description: 'Identifier for the tax rate, unique for the company in the accounting software.'
example: d2939064-dd3a-4c0f-9865-a238c2193515
name:
type: string
nullable: true
description: Codat-augmented name of the tax rate in the accounting software.
code:
type: string
nullable: true
description: Code for the tax rate from the accounting software.
effectiveTaxRate:
type: number
format: decimal
nullable: true
description: See Effective tax rates description.
totalTaxRate:
type: number
format: decimal
nullable: true
description: Total (not compounded) sum of the components of a tax rate.
status:
title: Tax rate status
type: string
enum:
- Active
- Archived
description: |-
Status of the tax rate in the accounting software.
- `Active` - An active tax rate in use by a company.
- `Archived` - A tax rate that has been archived or is inactive in the accounting software.
accountStatus:
type: string
description: The current status of the account.
enum:
- Active
- Archived
example: Active
BillPayment:
title: Bill payment
type: object
description: ''
properties:
id:
type: string
description: 'Identifier for the bill payment, unique for the company in the accounting software.'
amount:
type: number
format: decimal
description: Amount of the payment in the bill currency.
example: 1329.54
date:
allOf:
- $ref: '#/components/schemas/Connection/properties/created'
- description: Date the bill payment was recorded in the accounting software.
reference:
type: string
nullable: true
description: Additional information associated with the payment.
example: Bill Payment against bill c13e37b6-dfaa-4894-b3be-9fe97bda9f44
accountRef:
$ref: '#/components/schemas/BillPayment/definitions/billPaymentAccountRef'
currencyRate:
$ref: '#/components/schemas/Bill/properties/currencyRate'
definitions:
billPaymentPrototype:
title: Bill payment prototype
type: object
properties:
amount:
$ref: '#/components/schemas/BillPayment/properties/amount'
date:
$ref: '#/components/schemas/BillPayment/properties/date'
reference:
$ref: '#/components/schemas/BillPayment/properties/reference'
accountRef:
$ref: '#/components/schemas/BillPayment/definitions/billPaymentAccountRef'
currencyRate:
$ref: '#/components/schemas/Bill/properties/currencyRate'
required:
- amount
- date
- accountRef
billPaymentAccountRef:
description: Reference to the bank account / credit card which you are using to pay the bill.
type: object
properties:
id:
type: string
description: Unique ID of the bank account / credit card
required:
- id
example:
amount: 22
date: '2022-10-23T00:00:00.000Z'
reference: Bill Payment against bill c13e37b6 dfaa-4894-b3be-9fe97bda9f44
accountRef:
id: 9e32cbf8-e7d5-4d4d-a593-08d550682aab
currencyRate: 1
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/Connection/properties/created'
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/Connection/properties/created'
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/Connection/properties/created'
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'
- $ref: '#/components/schemas/PagingInfo'
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/sync-for-payables-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/Connection/properties/created'
nullable: true
created:
$ref: '#/components/schemas/Connection/properties/created'
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
type: object
description: Gets the latest basic info for a company.
properties:
companyName:
type: string
nullable: true
description: Name of the linked company.
baseCurrency:
type: string
nullable: true
description: Currency set in the accounting software of the linked company. Used by the currency rate.
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
Connection:
title: Connection
description: "\uFEFFA connection represents a [company's](https://docs.codat.io/sync-for-payables-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/Connection/properties/created'
nullable: true
created:
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.
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/Connection/properties/created'
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/Connection/properties/created'
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/PagingInfo'
DataStatus:
title: Data status
description: Describes the state of data in the Codat cache for a company and data type
type: object
required:
- dataType
- lastSuccessfulSync
- currentStatus
properties:
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
lastSuccessfulSync:
$ref: '#/components/schemas/Connection/properties/created'
currentStatus:
$ref: '#/components/schemas/PullOperation/properties/status'
latestSyncId:
type: string
description: Unique identifier for most recent sync of data type.
format: uuid
example: ad474a37-2003-478e-baee-9af9f1ec2fe3
latestSuccessfulSyncId:
type: string
description: Unique identifier for the most recent successful sync of data type.
format: uuid
example: 8220fc90-55b6-47bc-9417-48ac6ea93101
examples:
- dataType: string
lastSuccessfulSync: '2022-01-01T13:00:00.000Z'
currentStatus: string
latestSyncId: ad474a37-2003-478e-baee-9af9f1ec2fe3
latestSuccessfulSyncId: 8220fc90-55b6-47bc-9417-48ac6ea93101
DataType:
x-internal: true
$ref: '#/components/schemas/DataStatus/properties/dataType'
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.
Pagination:
title: Pagination metadata
x-internal: true
type: object
properties:
continuationToken:
type: string
description: 'A continuation token indicating there are more results to be fetched. Supply this value in the `continuationToken` query parameter in the next request to fetch the next set of results. Once no more results are available, the continuation token will not be present in the response.'
PagingInfo:
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/PagingInfo/definitions/links'
definitions:
links:
title: Hal Links
type: object
required:
- self
- current
properties:
self:
$ref: '#/components/schemas/PagingInfo/definitions/halRef'
current:
$ref: '#/components/schemas/PagingInfo/definitions/halRef'
next:
$ref: '#/components/schemas/PagingInfo/definitions/halRef'
previous:
$ref: '#/components/schemas/PagingInfo/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'
PaymentMappingOptions:
x-internal: true
title: Mapping Options Payments
description: Gets the bill payments mapping options for a company's accounting software
type: object
properties:
bankAccounts:
type: array
items:
$ref: '#/components/schemas/PaymentMappingOptions/definitions/bankAccountMappingOption'
pagination:
$ref: '#/components/schemas/Pagination'
definitions:
bankAccountMappingOption:
title: Bank account mapping option
type: object
allOf:
- properties:
id:
type: string
description: 'Identifier for the account, unique for the company in the accounting software.'
example: 3d5a8e00-d108-4045-8823-7f342676cffa
name:
type: string
nullable: true
description: Name of the bank account in the accounting software.
example: Bank of Dave current account
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.
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.
currency:
type: string
nullable: true
description: The bank account's base currency.
status:
$ref: '#/components/schemas/PaymentMappingOptions/definitions/bankAccountStatus'
accountType:
$ref: '#/components/schemas/BankAccount/allOf/0/properties/accountType'
- $ref: '#/components/schemas/Attachment/allOf/1'
bankAccountStatus:
type: string
description: The current status of the bank account.
enum:
- Active
- Archived
example: Active
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/Connection/properties/created'
completed:
$ref: '#/components/schemas/Connection/properties/created'
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/PagingInfo'
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/DataStatus/properties/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/Connection/properties/created'
description: The datetime when the push was requested.
completedOnUtc:
$ref: '#/components/schemas/Connection/properties/created'
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/DataStatus/properties/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/PagingInfo'
Supplier:
title: Supplier
description: "\uFEFFSuppliers are people or organizations that provide something, such as a product or service. Use the [List suppliers](https://docs.codat.io/sync-for-payables-v2-api#/operations/list-suppliers) endpoint to retrieve a list of all suppliers for a company.\n\nSuppliers' data links to accounts payable [bills](https://docs.codat.io/sync-for-payables-v2-api#/schemas/Bill).\n "
type: object
properties:
id:
type: string
description: 'Identifier for the supplier, unique to the company in the accounting software.'
supplierName:
type: string
description: 'Name of the supplier as recorded in the accounting system, typically the company name.'
contactName:
type: string
nullable: true
description: Name of the main contact for the supplier.
emailAddress:
type: string
nullable: true
description: Email address that the supplier may be contacted on.
phone:
type: string
nullable: true
description: Phone number that the supplier may be contacted on.
examples:
- +44 25691 154789
- (877) 492-8687
- 01224 658 999
addresses:
type: array
nullable: true
description: An array of Addresses.
items:
$ref: '#/components/schemas/Address'
status:
$ref: '#/components/schemas/Supplier/definitions/supplierStatus'
balance:
type: number
format: decimal
nullable: true
description: Amount outstanding against the supplier.
defaultCurrency:
type: string
nullable: true
description: Default currency the supplier's transactional data is recorded in.
sourceModifiedDate:
allOf:
- $ref: '#/components/schemas/Connection/properties/created'
- 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:
supplierPrototype:
title: Supplier prototype
type: object
properties:
supplierName:
$ref: '#/components/schemas/Supplier/properties/supplierName'
contactName:
$ref: '#/components/schemas/Supplier/properties/contactName'
emailAddress:
$ref: '#/components/schemas/Supplier/properties/emailAddress'
phone:
$ref: '#/components/schemas/Supplier/properties/phone'
addresses:
$ref: '#/components/schemas/Supplier/properties/addresses'
status:
$ref: '#/components/schemas/Supplier/definitions/supplierStatus'
balance:
$ref: '#/components/schemas/Supplier/properties/balance'
defaultCurrency:
$ref: '#/components/schemas/Supplier/properties/defaultCurrency'
required:
- supplierName
- status
supplierRef:
title: Supplier reference
description: Reference to the supplier the record relates to.
type: object
properties:
id:
minLength: 1
type: string
description: The supplier's unique ID
supplierName:
type: string
nullable: true
description: The supplier's name
required:
- id
supplierStatus:
description: Status of the supplier.
type: string
enum:
- Unknown
- Active
- Archived
suppliers:
title: Suppliers
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Supplier'
pagination:
$ref: '#/components/schemas/Pagination'
examples:
- id: C520FFD4-F6F6-4FC2-A6D2-5D7088B2B14F
supplierName: Kelly's Industrial Supplies
contactName: Kelly Ipsum
emailAddress: sales@kellysupplies.com
phone: 07999 999999
addresses:
- type: Billing
line1: Unit 51
line2: Bakersfield Industrial Estate
city: Bakersfield
region: California
country: USA
postalcode: '93308'
status: Active
amount: 100
defaultCurrency: GBP
sourceModifiedDate: '2022-10-23T00:00:00Z'
parameters:
attachmentId:
name: attachmentId
in: path
required: true
schema:
type: string
format: uuid
example: 8a210b68-6988-11ed-a1eb-0242ac120002
description: Unique identifier for an attachment.
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).'
billId:
name: billId
in: path
required: true
schema:
type: string
examples:
- 13d946f0-c5d5-42bc-b092-97ece17923ab
- 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2
- 7110701885
- EILBDVJVNUAGVKRQ
description: Unique identifier for a bill.
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.
continuationToken:
name: continuationToken
in: query
required: false
schema:
type: string
example: continuationToken=eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==
description: Retrieve the next page of results using the continuation token from the previous response.
statusQuery:
name: statusQuery
in: query
required: false
schema:
type: string
example: status=Archived
description: 'Codat query string allows you to filter by `status` (`status=Active||status=Archived`). [Learn more](https://docs.codat.io/using-the-api/querying) about Codat''s query string.'
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
Idempotency-Conflict:
description: A request is in progress with the same idempotency key.
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/sync-for-payables-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)