openapi: 3.1.0
x-stoplight:
id: 466k6ayziv9at
servers:
- description: Production
url: 'https://api.codat.io'
info:
title: Platform API
version: 3.0.0
summary: Platform API
description: |-
An API for the common components of all of Codat's products.
These end points cover creating and managing your companies, data connections, and integrations.
[Read about the building blocks of Codat...](https://docs.codat.io/core-concepts/companies) | [See our 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. |
| Connection management | Configure connection management UI and retrieve access tokens for authentication. |
| Webhooks | Create and manage webhooks that listen to Codat's events. |
| Integrations | Get a list of integrations supported by Codat and their logos. |
| Refresh data | Initiate data refreshes, view pull status and history. |
| Settings | Manage company profile configuration, sync settings, and API keys. |
| Push data | Initiate and monitor Create, Update, and Delete operations. |
| Supplemental data | Configure and pull additional data you can include in Codat's standard data types. |
| Custom data type | Configure and pull additional data types that are not included in Codat's standardized data model. |
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: platform-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: Connection management
description: Configure UI and retrieve access tokens for authentication used by **Connections SDK**.
- name: Webhooks
description: Create and manage webhooks that listen to Codat's events.
- name: Integrations
description: Get a list of integrations supported by Codat and their logos.
- name: Refresh data
description: 'Initiate data refreshes, view pull status and history.'
- name: Settings
description: 'Manage company profile configuration, sync settings, and API keys.'
- name: Push data
description: 'Initiate and monitor Create, Update, and Delete operations.'
- name: Supplemental data
description: Configure and pull additional data you can include in Codat's standard data types.
- name: Custom data type
description: Configure and pull additional data types that are not included in Codat's standardized data model.
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/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-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/Bad-Request'
'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/platform-api#/schemas/Company) that represents your customer in Codat. \n\nA [company](https://docs.codat.io/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-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}':
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/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n"
parameters:
- $ref: '#/components/parameters/companyId'
tags:
- Companies
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
examples:
Simple company:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: My First Company
description: ''
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18Z'
createdByUserName: Dan Tzabar
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
delete:
summary: Delete a company
operationId: delete-company
parameters:
- $ref: '#/components/parameters/companyId'
description: "\uFEFFThe *Delete company* endpoint permanently deletes a [company](https://docs.codat.io/platform-api#/schemas/Company), its [connections](https://docs.codat.io/platform-api#/schemas/Connection) and any cached data. This operation is irreversible.\n\nA [company](https://docs.codat.io/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n"
tags:
- Companies
responses:
'204':
description: No Content
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
put:
summary: Update company
description: "\uFEFFUse the *Update company* endpoint to update both the name and description of the company. \n\nA [company](https://docs.codat.io/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data."
operationId: update-company
parameters:
- $ref: '#/components/parameters/companyId'
tags:
- Companies
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyRequestBody'
examples:
Update name:
value:
name: New Name
Update description:
value:
name: Same name
description: Additional documents required
'/companies/{companyId}/products/{productIdentifier}':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/productIdentifier'
put:
summary: Add product
operationId: add-product
x-speakeasy-name-override: add-product
description: |-
Use the *Add product* endpoint to enable a product for the company specified by `companyId`.
> Note: This feature is currently in alpha and available only to participants in the development program.
tags:
- Companies
responses:
'204':
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'
delete:
summary: Remove product
operationId: remove-product
x-speakeasy-name-override: remove-product
description: |-
Use the *Remove product* endpoint to disable a product for the company specified by `companyId`.
> Note: This feature is currently in alpha and available only to participants in the development program.
tags:
- Companies
responses:
'204':
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'
'/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/platform-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:
$ref: '#/components/parameters/platformKey/schema'
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:
$ref: '#/components/schemas/UpdateConnectionStatus'
examples:
Example:
value:
status: Unlinked
description: ''
'/companies/{companyId}/connections/{connectionId}/authorization':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
put:
summary: Update authorization
operationId: update-connection-authorization
x-speakeasy-name-override: update-authorization
description: Update data connection's authorization.
tags:
- Connections
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:
type: object
additionalProperties:
type: string
description: ''
'/companies/{companyId}/connectionManagement/accessToken':
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: Get access token
operationId: get-connection-management-access-token
x-speakeasy-name-override: get-access-token
tags:
- Connection management
description: "\uFEFFUse the *Get access token* endpoint to retrieve a new access token for use with the [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management). The token is only valid for one hour and applies to a single company.\n\nThe embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) lets your customers control access to their data by allowing them to manage their existing connections."
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionManagementAccessToken'
examples:
Access token:
value:
accessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
'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'
/connectionManagement/corsSettings:
get:
summary: Get CORS settings
operationId: get-connection-management-cors-settings
x-speakeasy-group: connection-management.cors-settings
tags:
- Connection management
description: "\uFEFFThe *Get CORS settings* endpoint returns the allowed origins (i.e. your domains) you want to allow cross-origin resource sharing ([CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)) with Codat. \n\nEnabling CORS with Codat is required by our embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) to access Codat's API endpoints.\n\nThe embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) lets your customers control access to their data by allowing them to manage their existing connections."
responses:
'200':
$ref: '#/components/responses/ConnectionManagementAllowedOrigins'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
post:
summary: Set CORS settings
operationId: set-connection-management-cors-settings
x-speakeasy-name-override: set
x-speakeasy-group: connection-management.cors-settings
tags:
- Connection management
description: "\uFEFFThe *Set CORS settings* endpoint allows you to register allowed origins (i.e. your domains) for use in cross-origin resource sharing ([CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)).\n \nEnabling CORS with Codat is required by our embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) to access Codat's API endpoints. \n\nThe embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) lets your customers control access to their data by allowing them to manage their existing connections."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionManagementAllowedOrigins'
examples:
Allowed origins:
$ref: '#/components/examples/connectionManagementAllowedOriginsResponse'
responses:
'200':
$ref: '#/components/responses/ConnectionManagementAllowedOrigins'
'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}/data/all':
parameters:
- $ref: '#/components/parameters/companyId'
post:
summary: Refresh all data
operationId: refresh-company-data
x-speakeasy-name-override: all
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'
description: |-
Refreshes all data types with `fetch on first link` set to `true` for a given company.
This is an asynchronous operation, and will bring updated data into Codat from the linked integration for you to view.
[Read more](https://docs.codat.io/core-concepts/data-type-settings) about data type settings and `fetch on first link`.
tags:
- Refresh data
'/companies/{companyId}/data/queue/{dataType}':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/dataType'
post:
summary: Refresh data type
operationId: refresh-data-type
x-speakeasy-name-override: by-data-type
description: |-
Refreshes a given data type for a given company.
This is an asynchronous operation, and will bring updated data into Codat from the linked integration for you to view.
tags:
- Refresh data
parameters:
- schema:
type: string
format: uuid
in: query
name: connectionId
description: 'Optionally, provide a data connection id to only queue pull operations on that connection.'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PullOperation'
'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}/dataStatus':
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: Get data status
operationId: get-company-data-status
description: Get the state of each data type for a company
tags:
- Refresh data
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DataStatuses'
examples:
Example:
value:
accountTransactions:
dataType: accountTransactions
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
balanceSheet:
dataType: balanceSheet
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
bankAccounts:
dataType: bankAccounts
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
bankTransactions:
dataType: bankTransactions
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
billCreditNotes:
dataType: billCreditNotes
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
billPayments:
dataType: billPayments
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
bills:
dataType: bills
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
cashFlowStatement:
dataType: cashFlowStatement
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
chartOfAccounts:
dataType: chartOfAccounts
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
company:
dataType: company
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
creditNotes:
dataType: creditNotes
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
customers:
dataType: customers
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
directCosts:
dataType: directCosts
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
directIncomes:
dataType: directIncomes
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
invoices:
dataType: invoices
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
itemReceipts:
dataType: itemReceipts
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
items:
dataType: items
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
journalEntries:
dataType: journalEntries
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
journals:
dataType: journals
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
paymentMethods:
dataType: paymentMethods
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
payments:
dataType: payments
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
profitAndLoss:
dataType: profitAndLoss
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
purchaseOrders:
dataType: purchaseOrders
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
salesOrders:
dataType: salesOrders
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
suppliers:
dataType: suppliers
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
taxRates:
dataType: taxRates
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
trackingCategories:
dataType: trackingCategories
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
transfers:
dataType: transfers
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
banking-accountBalances:
dataType: banking-accountBalances
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
banking-accounts:
dataType: banking-accounts
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
banking-transactionCategories:
dataType: banking-transactionCategories
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
banking-transactions:
dataType: banking-transactions
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-companyInfo:
dataType: commerce-companyInfo
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-customers:
dataType: commerce-customers
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-disputes:
dataType: commerce-disputes
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-locations:
dataType: commerce-locations
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-orders:
dataType: commerce-orders
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-paymentMethods:
dataType: commerce-paymentMethods
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-payments:
dataType: commerce-payments
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-productCategories:
dataType: commerce-productCategories
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-products:
dataType: commerce-products
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-taxComponents:
dataType: commerce-taxComponents
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
commerce-transactions:
dataType: commerce-transactions
lastSuccessfulSync: '2022-01-01T00:00:00.000Z'
currentStatus: Complete
latestSyncId: d03b6979-eb3b-447a-a27a-13cf457a9f48
latestSuccessfulSyncId: 6883bba8-514d-423f-ba7f-c38285a80b7f
'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}/data/history':
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: List pull operations
tags:
- Refresh data
operationId: list-pull-operations
x-speakeasy-name-override: list-pull-operations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PullOperations'
examples:
Example:
value:
results:
- id: 97d60846-f07a-4d42-b5a0-0bdcc6ebf56b
companyId: 4645bd78-8988-45bc-ac9e-67ba5df6e4e5
connectionId: 51baa045-4836-4317-a42e-3542e991e581
dataType: invoices
status: Initial
requested: '2022-11-14T11:18:37.2798351Z'
progress: 10
isCompleted: false
isErrored: false
_links:
current:
href: /companies/17129e41-5389-4f10-ac06-e0a37e47d177/data/history?page=1&pageSize=2
self:
href: /companies/17129e41-5389-4f10-ac06-e0a37e47d177/data/history
next:
href: /companies/17129e41-5389-4f10-ac06-e0a37e47d177/data/history?page=2&pageSize=2
pageNumber: 0
pageSize: 0
totalResults: 0
'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'
description: Gets the pull operation history (datasets) for a given company.
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
'/companies/{companyId}/data/history/{datasetId}':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/datasetId'
get:
summary: Get pull operation
operationId: get-pull-operation
x-speakeasy-name-override: get-pull-operation
tags:
- Refresh data
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PullOperation'
examples: {}
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
description: Retrieve information about a single dataset or pull operation.
/rules:
get:
summary: List webhooks (legacy)
operationId: list-rules
description: |-
Use the *List webhooks (legacy)* endpoint to retrieve all existing rule-based webhooks for your client.
**Note:** This endpoint has been deprecated. Please use the [*List webhook consumers*](https://docs.codat.io/platform-api#/operations/list-webhook-consumers) endpoint for listing webhooks moving forward.
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
deprecated: true
tags:
- Webhooks
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook/definitions/webhooks'
examples:
Example:
value:
results:
- id: fcfbfe0b-fe73-47ed-a7fe-0018567f5da2
type: DataConnectionStatusChanged
notifiers:
emails: []
webhook: 'https://webhook.site/6d385ea9-bcf9-48e4-9103-1958ccb54997'
pageNumber: 1
pageSize: 100
totalResults: 1
_links:
current:
href: /rules?page=1&pageSize=100
self:
href: /rules
'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 webhook (legacy)
description: |-
Use the *Create webhooks (legacy)* endpoint to create a rule-based webhook for your client.
**Note:** This endpoint has been deprecated. Please use the [*Create webhook consumer*](https://docs.codat.io/platform-api#/operations/create-webhook-consumer) endpoint to create a webhook moving forward.
operationId: create-rule
deprecated: true
tags:
- Webhooks
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook/definitions/createRule'
examples:
Company data connection status changed:
value:
type: DataConnectionStatusChanged
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
New company synchronized:
value:
type: New company synchronised
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
Data sync completed:
value:
type: Data sync completed
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
Dataset data changed:
value:
type: Dataset data changed
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
Dataset status has changed to an error state:
value:
type: Data Sync Status Changed To Error
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
Push operation status has changed:
value:
type: Push Operation Status Changed
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
Push operation has timed out:
value:
type: Push Operation Timed Out
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
Account categories updated:
value:
type: Account Categories Updated
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
Sync Connection Deleted:
value:
type: Sync Connection Deleted
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
description: Create a webhook with the given configuration.
'/rules/{ruleId}':
parameters:
- $ref: '#/components/parameters/ruleId'
get:
summary: Get webhook (legacy)
operationId: get-webhook
description: |-
Use the *Get webhook (legacy)* endpoint to retrieve a specific webhook for your client.
**Note:** This endpoint has been deprecated. Please use the [*List webhook consumers*](https://docs.codat.io/platform-api#/operations/list-webhook-consumers) endpoint for listing webhooks moving forward.
deprecated: true
tags:
- Webhooks
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
examples: {}
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
/webhooks:
get:
summary: List webhook consumers
operationId: list-webhook-consumers
x-speakeasy-name-override: list-consumers
description: "\uFEFFUse the *List webhook consumers* endpoint to return a list of all webhook consumers that currently exist for your client.\n\n[Webhook consumer](https://docs.codat.io/platform-api#/schemas/WebhookConsumer) is an HTTP endpoint that you configure to subscribe to specific events. See our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview)."
tags:
- Webhooks
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookConsumer/definitions/webhookConsumers'
examples:
Webhook consumers:
value:
results:
- id: 12571faf-0898-47e7-afdd-0fe9eb0a9bf5
url: 'https://example.com/webhoook-consumers/sync-complete'
eventTypes:
- DataSyncCompleted
disabled: false
- id: ca3cac86-7925-4759-abc2-96405780fdfa
url: 'https://example.com/webhoook-consumers/dataset-changed'
eventTypes:
- DatasetDataChanged
disabled: true
'400':
$ref: '#/components/responses/Bad-Request'
'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'
post:
summary: Create webhook consumer
operationId: create-webhook-consumer
x-speakeasy-name-override: create-consumer
description: "\uFEFFUse the *Create webhook consumer* endpoint to create a new webhook consumer that will listen to messages we send you.\n\n[Webhook consumer](https://docs.codat.io/platform-api#/schemas/WebhookConsumer) is an HTTP endpoint that you configure to subscribe to specific events. See our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview).\n\n### Tips and traps\n- The number of webhook consumers you can create is limited to 50. If you have reached the maximum number of consumers, use the [*Delete webhook consumer*](https://docs.codat.io/platform-api#/operations/delete-webhook-consumer) endpoint to delete an unused consumer first."
tags:
- Webhooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookConsumer/definitions/webhookConsumerPrototype'
examples:
Subscribe consumer to one or more event types:
value:
url: 'https://example.com/webhoook-consumer'
eventTypes:
- DataSyncCompleted
- Dataset data changed
Subscribe consumer with disabled endpoint:
value:
url: 'https://example.com/webhoook-consumer'
eventTypes:
- DataSyncCompleted
disabled: true
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookConsumer'
examples:
Subscribe consumer to one or more event types:
value:
id: 12571faf-0898-47e7-afdd-0fe9eb0a9bf5
url: 'https://example.com/webhoook-consumer'
eventTypes:
- DataSyncCompleted
- DatasetDataChanged
disabled: false
Subscribe consumer with disabled endpoint:
value:
id: 12571faf-0898-47e7-afdd-0fe9eb0a9bf5
url: 'https://example.com/webhoook-consumer'
eventTypes:
- DataSyncCompleted
disabled: true
'400':
$ref: '#/components/responses/Bad-Request'
'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'
'/webhooks/{webhookId}':
parameters:
- $ref: '#/components/parameters/webhookId'
delete:
summary: Delete webhook consumer
operationId: delete-webhook-consumer
x-speakeasy-name-override: delete-consumer
description: "\uFEFFUse the *Delete webhook consumer* endpoint to delete an existing webhoook consumer, providing its valid `id` as a parameter.\n\n[Webhook consumer](https://docs.codat.io/platform-api#/schemas/WebhookConsumer) is an HTTP endpoint that you configure to subscribe to specific events. See our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview)."
tags:
- Webhooks
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'
/webhooks/integrationKeys/zapier:
post:
summary: Rotate Zapier key
operationId: rotate-zapier-key
x-speakeasy-ignore: true
description: "\uFEFFThe *Rotate Zapier key* endpoint returns the Zapier integration key needed to configure Zaps triggered by Codat's webhooks. \n\nIf a key has already been created, calling this will revoke that existing key.\n\nThe key changes each time this endpoint is called. If you are already using our Zapier integration and called this endpoint again, you need to reauthenticate using the latest integration key returned in the response.\n\nOur Zapier integration makes it simple for you to set up and receive user notifications in your preferred ways, such as via email or Slack. See our [Zapier documentation](https://docs.codat.io/using-the-api/webhooks/zapier-integration) for detailed instructions on setting up this integration.\n\n"
tags:
- Webhooks
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookZapierKey'
examples:
Integration key:
value:
key: sk_integ_WM4dfoK1nKZnDE_kceze6hWDjbRwOZwG.us
'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'
/integrations:
get:
summary: List integrations
description: List your available integrations
tags:
- Integrations
operationId: list-integrations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Integrations'
'400':
$ref: '#/components/responses/Malformed-Query'
'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'
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
'/integrations/{platformKey}':
parameters:
- $ref: '#/components/parameters/platformKey'
get:
summary: Get integration
tags:
- Integrations
operationId: get-integration
description: 'Get single integration, by platformKey'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Integration'
'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'
'/integrations/{platformKey}/branding':
parameters:
- $ref: '#/components/parameters/platformKey'
get:
summary: Get branding
tags:
- Integrations
operationId: get-integrations-branding
x-speakeasy-name-override: get-branding
description: Get branding for platform.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Branding'
'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'
/profile:
get:
summary: Get profile
tags:
- Settings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
examples: {}
'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'
operationId: get-profile
x-speakeasy-name-override: get-profile
description: Fetch your Codat profile.
put:
summary: Update profile
operationId: update-profile
x-speakeasy-name-override: update-profile
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
examples: {}
'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'
tags:
- Settings
description: Update your Codat profile
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
examples: {}
description: All fields should be included when updating your profile.
/profile/syncSettings:
get:
summary: Get sync settings
tags:
- Settings
operationId: get-profile-syncSettings
x-speakeasy-name-override: get-sync-settings
description: 'Retrieve the [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings) for your client. This includes how often data types should be queued to be updated, and how much history should be fetched.'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SyncSettings'
examples:
Example:
value:
clientId: 367f7975-267b-439b-90c6-a6040ee680f3
settings:
- dataType: invoices
fetchOnFirstLink: true
syncSchedule: 24
syncOrder: 0
syncFromUtc: '2020-01-01T12:00:00.000Z'
syncFromWindow: 24
monthsToSync: 24
isLocked: true
overridesDefaults: true
'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'
post:
summary: Update all sync settings
description: Update sync settings for all data types.
tags:
- Settings
operationId: update-profile-syncSettings
x-speakeasy-name-override: update-sync-settings
responses:
'204':
description: No Content
'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'
requestBody:
content:
application/json:
schema:
allOf:
- properties:
clientId:
$ref: '#/components/schemas/ClientId'
settings:
type: array
items:
$ref: '#/components/schemas/SyncSetting'
overridesDefaults:
type: boolean
default: true
description: 'Set to `True` if you want to override default [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings).'
required:
- clientId
- settings
- overridesDefaults
type: object
description: |-
Include a `syncSetting` object for each data type.
`syncFromWindow`, `syncFromUTC` & `monthsToSync` only need to be included if you wish to set a value for them.
/apiKeys:
get:
summary: List API keys
description: |-
Use the *List API keys* endpoint to return a list of all API keys that currently exist for your client. This includes keys created via the Portal UI or the *Create API keys* endpoint.
[API keys](https://docs.codat.io/platform-api#/schemas/apiKeys) are tokens used to control access to the API. Include this token in the `Authorization` header parameter when making API calls, following the word "Basic" and a space with your API key.
You can [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat and managing API keys via the Portal UI or API.
operationId: list-api-keys
x-speakeasy-name-override: list-api-keys
tags:
- Settings
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeys'
examples:
Example:
value:
results:
- id: 0498e921-9b53-4396-a412-4f2f5983b0a2
apiKey: ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd
createdDate: '2022-04-11T13:49:37Z'
- id: c438836a-61fe-443f-8a19-24cc18be21e4
name: azure-invoice-finance-processor
apiKey: ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd
createdDate: '2022-04-23T09:43:48Z'
'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'
post:
summary: Create API key
operationId: create-api-key
x-speakeasy-name-override: create-api-key
description: |-
Use the *Create API keys* endpoint to generate a new API key for your client.
[API keys](https://docs.codat.io/platform-api#/schemas/apiKeys) are tokens used to control access to the API. Include this token in the `Authorization` header parameter when making API calls, following the word "Basic" and a space with your API key.
You can [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat and managing API keys via the Portal UI or API.
### Tips and pitfalls
* Your first API key is created for you. Access this key via [Codat's Portal](https://app.codat.io/developers/api-keys).
* If you require multiple API keys, perform multiple calls to the *Create API keys* endpoint.
* The number of API keys is limited to 10. If you have reached the maximum amount of keys, use the *Delete API key* endpoint to delete an unused key first.
tags:
- Settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKey'
examples:
Create API key with name:
value:
name: azure-invoice-finance-processor
responses:
'201':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyDetails'
examples:
API key details:
value:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
apiKey: ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd
createdDate: '2022-04-11T13:49:37Z'
API key details with name:
value:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: azure-invoice-finance-processor
apiKey: ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd
createdDate: '2022-04-11T13:49:37Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Max length for name reached:
value:
statusCode: 400
service: PublicApi
error: Max string length (50) for `name` reached.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Max length for name reached:
value:
statusCode: 400
service: PublicApi
error: 'Maximum number of API keys reached. To create a new API key, delete an unused key and try again.'
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'/apiKeys/{apiKeyId}':
delete:
summary: Delete API key
operationId: delete-api-key
x-speakeasy-name-override: delete-api-key
parameters:
- name: apiKeyId
in: path
required: true
schema:
type: string
example: 8a210b68-6988-11ed-a1eb-0242ac120002
description: Unique identifier for api key.
description: |-
Use the *Delete API keys* endpoint to delete an existing API key, providing its valid `id` as a parameter. Note that this operation is not reversible.
[API keys](https://docs.codat.io/platform-api#/schemas/apiKeys) are tokens used to control access to the API. Include this token in the `Authorization` header parameter when making API calls, following the word "Basic" and a space with your API key.
You can [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat and managing API keys via the Portal UI or API.
### Tips and pitfalls
* It is possible to delete the last remaining API key. If this happens, a new key can be created via the [API key management page](https://app.codat.io/developers/api-keys) of the Portal.
* It is possible to delete the API key used to authenticate the *Delete API key* request.
tags:
- Settings
responses:
'204':
description: No Content
$ref: '#/components/responses/Too-Many-Requests'
'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}/options/{dataType}':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/dataType'
get:
summary: Get push options
tags:
- Push data
operationId: get-create-update-model-options-by-data-type
x-speakeasy-name-override: get-model-options
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PushOption'
examples: {}
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
description: |-
This is the generic documentation for creation and updating of data. See the equivalent endpoint for a given data type for more specific information.
Before pushing data into accounting software, it is often necessary to collect some details from the user as to how they would like the data to be inserted. This includes names and amounts on transactional entities, but also factors such as categorisation of entities, which is often handled differently between different accounting software. A good example of this is specifying where on the balance sheet/profit and loss reports the user would like a newly-created nominal account to appear.
Codat tries not to limit users to pushing to a very limited number of standard categories, so we have implemented "options" endpoints, which allow us to expose to our clients the fields which are required to be pushed for a specific linked company, and the options which may be selected for each field.
> **Supported Integrations**
>
> Check out our [coverage explorer](https://knowledge.codat.io/) for integrations that support push (POST/PUT methods).
'/companies/{companyId}/push':
parameters:
- $ref: '#/components/parameters/companyId'
get:
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
summary: List push operations
tags:
- Push data
operationId: get-company-push-history
x-speakeasy-name-override: list-operations
description: |-
The **List push operations** endpoint returns a list of [push operations](/using-the-api/push) performed on the company.
Write operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PushOperations'
examples: {}
'400':
$ref: '#/components/responses/Malformed-Query'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'/companies/{companyId}/push/{pushOperationKey}':
parameters:
- $ref: '#/components/parameters/companyId'
- schema:
type: string
format: uuid
name: pushOperationKey
in: path
required: true
description: Push operation key.
get:
summary: Get push operation
tags:
- Push data
operationId: get-push-operation
x-speakeasy-name-override: get-operation
description: |-
The **Get push operation** endpoint returns a specific [push operation](/using-the-api/push) identified by the `pushOperationKey` that was performed on the company.
Write operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PushOperation'
examples: {}
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'/integrations/{platformKey}/dataTypes/{dataType}/supplementalDataConfig':
parameters:
- $ref: '#/components/parameters/platformKey'
- name: dataType
in: path
required: true
description: Supported supplemental data data type.
schema:
x-internal: true
type: string
description: Data types that support supplemental data
enum:
- chartOfAccounts
- bills
- company
- creditNotes
- customers
- invoices
- items
- journalEntries
- suppliers
- taxRates
- commerce-companyInfo
- commerce-customers
- commerce-disputes
- commerce-locations
- commerce-orders
- commerce-payments
- commerce-paymentMethods
- commerce-products
- commerce-productCategories
- commerce-taxComponents
- commerce-transactions
example: invoices
put:
summary: Configure
description: |-
The *Configure* endpoint allows you to maintain or change configuration required to return supplemental data for each integration and data type combination.
[Supplemental data](https://docs.codat.io/using-the-api/additional-data) is additional data you can include in Codat's standard data types.
**Integration-specific behaviour**
See the *examples* for integration-specific frequently requested properties.
operationId: configure-supplemental-data
x-speakeasy-name-override: configure
tags:
- Supplemental data
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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SupplementalDataConfiguration'
examples:
Xero - Accounts:
value:
yourKeyNameForAccounts:
dataSource: /Accounts
pullData:
yourNameForTaxType: TaxType
yourNameForSystemAccount: SystemAccount
Xero - Invoices:
value:
yourKeyNameForInvoices:
dataSource: /Invoices
pullData:
yourNameForExpectedPaymentDate: ExpectedPaymentDate
yourNameForHasAttachments: HasAttachments
Xero - Items:
value:
yourKeyNameForItems:
dataSource: /Items
pullData:
yourNameForQuantityOnHand: QuantityOnHand
yourNameForTotalCostPool: TotalCostPool
Xero - Contacts:
value:
yourKeyNameForContacts:
dataSource: /Contacts
pullData:
yourNameForBankAccounts: BankAccountDetails
Xero - Tax rates:
value:
yourKeyNameForTaxRates:
dataSource: /TaxRates
pullData:
yourNameForCanApplyToLiabilities: CanApplyToLiabilities
yourNameForCanApplyToAssets: CanApplyToAssets
yourNameForCanApplyToEquity: CanApplyToEquity
yourNameForCanApplyToExpenses: CanApplyToExpenses
yourNameForCanApplyToRevenue: CanApplyToRevenue
QBO - Customers:
value:
yourKeyNameForCustomers:
dataSource: /Customer
pullData:
yourNameForSalesTermRef: SalesTermRef.value
yourNameForParentRef: ParentRef.value
QBO - Invoices:
value:
yourKeyNameForInvoices:
dataSource: /Invoice
pullData:
yourNameForSalesTermRef: SalesTermRef.value
description: The configuration for the specified platform and data type.
get:
summary: Get configuration
description: |-
The *Get configuration* endpoint returns supplemental data configuration previously created for each integration and data type combination.
[Supplemental data](https://docs.codat.io/using-the-api/additional-data) is additional data you can include in Codat's standard data types.
operationId: get-supplemental-data-configuration
x-speakeasy-name-override: get-configuration
tags:
- Supplemental data
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SupplementalDataConfiguration'
'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'
'/integrations/{platformKey}/dataTypes/custom/{customDataIdentifier}':
parameters:
- $ref: '#/components/parameters/platformKey'
- $ref: '#/components/parameters/customDataIdentifier'
put:
summary: Configure custom data type
description: |-
The *Configure custom data type* endpoint allows you to maintain or change the configuration required to return a custom data type for a specific integration.
A [custom data type](https://docs.codat.io/using-the-api/custom-data) is an additional data type you can create that is not included in Codat's standardized data model.
### Tips and traps
- You can only configure a single custom data type for a single platform at a time. Use the endpoint multiple times if you need to configure it for multiple platforms.
- You can only indicate a single data source for each customer data type.
- Make your custom configuration as similar as possible to our standard data types so you can interact with them in exactly the same way.
operationId: configure-custom-data-type
x-speakeasy-name-override: configure
tags:
- Custom data type
requestBody:
description: Custom data type configuration for the specified platform.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomDataTypeConfiguration'
examples:
Dynamics 365 Business Central:
value:
dataSource: api/purchaseOrders
requiredData:
currency: '$[*].currencyCode'
number: '$[*].number'
date: '$[*].orderDate'
totalexvat: '$[*].totalAmountExcludingTax'
totaltax: '$[*].totalTaxAmount'
vendor: '$[*].number'
keyBy:
- '$[*].id'
sourceModifiedDate:
- '$[*].lastModifiedDateTime'
Xero Simple Record:
value:
dataSource: /api.xro/2.0/Accounts
requiredData:
code: $.Code
accountId: $.AccountID
type: $.Type
SysAcc: $.SystemAccount
keyBy:
- $.AccountID
Xero Mapping Arrays:
value:
dataSource: /api.xro/2.0/Invoices
requiredData:
invNumber: $.InvoiceNumber
type: $.Type
InvoiceID: $.InvoiceID
lines: '$.LineItems[*]'
keyBy:
- $.InvoiceID
sourceModifiedDate:
- $.UpdatedDateUTC
QuickBooks Online:
value:
dataSource: /query?query=select * from Account
requiredData:
id: $.Id
Currentbal: $.CurrentBalance
SubAcc: $.SubAccount
keyBy:
- $.Id
sourceModifiedDate:
- $.time
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomDataTypeConfiguration'
examples:
Dynamics 365 Business Central:
value:
dataSource: api/purchaseOrders
requiredData:
currency: '$[*].currencyCode'
number: '$[*].number'
date: '$[*].orderDate'
totalexvat: '$[*].totalAmountExcludingTax'
totaltax: '$[*].totalTaxAmount'
vendor: '$[*].number'
keyBy:
- '$[*].id'
sourceModifiedDate:
- '$[*].lastModifiedDateTime'
Xero Simple Record:
value:
dataSource: /api.xro/2.0/Accounts
requiredData:
code: $.Code
accountId: $.AccountID
type: $.Type
SysAcc: $.SystemAccount
keyBy:
- $.AccountID
Xero Mapping Arrays:
value:
dataSource: /api.xro/2.0/Invoices
requiredData:
invNumber: $.InvoiceNumber
type: $.Type
InvoiceID: $.InvoiceID
lines: '$.LineItems[*]'
keyBy:
- $.InvoiceID
sourceModifiedDate:
- $.UpdatedDateUTC
QuickBooks Online:
value:
dataSource: /query?query=select * from Account
requiredData:
id: $.Id
Currentbal: $.CurrentBalance
SubAcc: $.SubAccount
keyBy:
- $.Id
sourceModifiedDate:
- $.time
'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 custom data configuration
description: |-
The *Get custom data configuration* endpoint returns existing configuration details for the specified custom data type and integration pair you previously configured.
A [custom data type](https://docs.codat.io/using-the-api/custom-data) is an additional data type you can create that is not included in Codat's standardized data model.
operationId: get-custom-data-type-configuration
x-speakeasy-name-override: get-configuration
tags:
- Custom data type
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomDataTypeRecords'
'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}/data/queue/custom/{customDataIdentifier}':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/customDataIdentifier'
post:
summary: Refresh custom data type
description: The *Refresh custom data type* endpoint refreshes the specified custom data type for a given company. This is an asynchronous operation that will sync updated data from the linked integration into Codat for you to view.
operationId: refresh-custom-data-type
x-speakeasy-name-override: refresh
tags:
- Custom data type
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PullOperation'
'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'
'451':
$ref: '#/components/responses/Legal-Reasons'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'/companies/{companyId}/connections/{connectionId}/data/custom/{customDataIdentifier}':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
- $ref: '#/components/parameters/customDataIdentifier'
get:
summary: List custom data type records
description: |-
The *List custom data type records* endpoint returns a paginated list of records pulled for the specified custom data type you previously configured.
A [custom data type](https://docs.codat.io/using-the-api/custom-data) is an additional data type you can create that is not included in Codat's standardized data model.s endpoint returns a paginated list of records whose schema is defined [Configure custom data type](https://docs.codat.io/platform-api#/operations/configure-custom-data-type)
operationId: list-custom-data-type-records
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
tags:
- Custom data type
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomDataTypeRecords'
'400':
$ref: '#/components/responses/Bad-Request'
'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'
'451':
$ref: '#/components/responses/Legal-Reasons'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
webhooks:
company.created:
post:
description: Called when a company is created in Codat.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyWebhook'
examples:
Company created:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
type: company.created
generatedDate: '2024-08-08T17:10:34.015Z'
payload:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Bank of Dave
description: Requested a loan for refurb.
redirect: 'https://link.codat.io/company/0498e921-9b53-4396-a412-4f2f5983b0a2'
lastSync: '2022-01-01T12:00:00.000Z'
created: '2022-01-01T12:00:00.000Z'
tags:
customerRegion: us
uid: 335a086e-8563-4b03-94e3-39544225ecb6
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
company.deleted:
post:
description: Called when a company is deleted in Codat.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyWebhook'
examples:
Company deleted:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
eventType: company.deleted
generatedDate: '2024-08-08T17:10:34.015Z'
payload:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Bank of Dave
description: Requested a loan for refurb.
redirect: 'https://link.codat.io/company/0498e921-9b53-4396-a412-4f2f5983b0a2'
lastSync: '2022-01-01T12:00:00.000Z'
created: '2022-01-01T12:00:00.000Z'
tags:
customerRegion: uk
uid: f6b0c253-16c7-4da1-a0c5-9c871e9c9d6c
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
connection.created:
post:
description: Called when a connection is created by the SMB.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionWebhook'
examples:
Connection created:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
type: connection.created
generatedDate: '2024-08-08T17:10:34.015Z'
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Bank of Dave
description: internal_id_mxO7rLfo
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
tags:
customerRegion: us
uid: 335a086e-8563-4b03-94e3-39544225ecb6
connection:
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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: PendingAuth
lastSync: 2022-10-27T10:22:43.646Z
created: 2022-10-27T09:53:29.000Z
sourceType: Banking
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
connection.connected:
post:
description: Called when a connection is successfully linked by the SMB.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionWebhook'
examples:
Connection connected:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
type: connection.connected
generatedDate: '2024-08-08T17:10:34.015Z'
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Bank of Dave
description: internal_id_mxO7rLfo
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
tags:
customerRegion: us
uid: 335a086e-8563-4b03-94e3-39544225ecb6
connection:
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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: 2022-10-27T10:22:43.646Z
created: 2022-10-27T09:53:29.000Z
sourceType: Banking
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
connection.disconnected:
post:
description: Called when a connection is disconnected either due to being unlinked or de-authorized by the SMB or integration.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionWebhook'
examples:
Unlinked:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
type: connection.disconnected
generatedDate: '2024-08-08T17:10:34.015Z'
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Bank of Dave
description: internal_id_mxO7rLfo
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
tags:
customerRegion: us
uid: 335a086e-8563-4b03-94e3-39544225ecb6
connection:
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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Unlinked
lastSync: 2022-10-27T10:22:43.646Z
created: 2022-10-27T09:53:29.000Z
sourceType: Banking
De-authorized:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
type: connection.disconnected
generatedDate: '2024-08-08T17:10:34.015Z'
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Bank of Dave
description: internal_id_mxO7rLfo
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
tags:
customerRegion: us
uid: 335a086e-8563-4b03-94e3-39544225ecb6
connection:
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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Deauthorized
lastSync: 2022-10-27T10:22:43.646Z
created: 2022-10-27T09:53:29.000Z
sourceType: Banking
dataConnectionErrors:
- statusCode: '401'
statusText: The integration de-authorized access to the connection.
errorMessage: The integration de-authorized access to the connection.
erroredOnUtc: 2022-12-27T09:53:29.000Z
status: Active
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
connection.reconnected:
post:
description: Called when a connection is reconnected after becoming disconnected.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionWebhook'
examples:
Reconnected:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
type: connection.reconnected
generatedDate: '2024-08-08T17:10:34.015Z'
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Bank of Dave
description: internal_id_mxO7rLfo
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
tags:
customerRegion: us
uid: 335a086e-8563-4b03-94e3-39544225ecb6
connection:
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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: 2022-10-27T10:22:43.646Z
created: 2022-10-27T09:53:29.000Z
sourceType: Banking
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
connection.deleted:
post:
description: Called when a connection is deleted.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionWebhook'
examples:
Deleted:
value:
id: ba29118f-5406-4e59-b05c-ba307ca38d01
type: connection.deleted
generatedDate: '2024-08-08T17:10:34.015Z'
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Bank of Dave
description: internal_id_mxO7rLfo
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
tags:
customerRegion: us
uid: 335a086e-8563-4b03-94e3-39544225ecb6
connection:
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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: 2022-10-27T10:22:43.646Z
created: 2022-10-27T09:53:29.000Z
sourceType: Banking
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
read.completed:
post:
description: Called when the fetch of data types for a product has completed.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReadCompletedWebhook'
examples:
Read completed:
value:
id: 743ec94a-8aa4-44bb-8bd4-e1855ee0e74b
eventType: read.completed
generatedDate: 2022-10-23T00:00:00.000Z
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Toft stores
description: Requested early access to the new financing scheme.
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
modifiedFromDate: 2022-10-23T00:00:00.000Z
dataTypes:
- connectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
dataType: invoices
recordsModified: false
status: Complete
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
read.completed.initial:
post:
description: Called when the initial fetch of data types for a product has been completed.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReadCompletedWebhook'
examples:
Initial:
value:
id: 743ec94a-8aa4-44bb-8bd4-e1855ee0e74b
eventType: read.completed.initial
generatedDate: 2022-10-23T00:00:00.000Z
payload:
referenceCompany:
id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: Toft stores
description: Requested early access to the new financing scheme.
links:
portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary'
modifiedFromDate: 2022-10-23T00:00:00.000Z
dataTypes:
- connectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
dataType: invoices
recordsModified: false
status: Complete
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
'{dataType}.write.successful':
post:
description: |
Indicates that a `dataType` has been successfully created, updated, deleted, or had an attachment uploaded in the accounting software.
Codat now refers to push operations as write requests.
For example, to subscribe to events where a bill is written into the accounting software, use the `bills.write.successful` webhook.
### Supported data types and write types
| `dataType` | Create | Update | Delete | UploadAttachment |
|------------------|---------|---------|---------|------------------|
| bankAccounts | ✅ | ✅ | - | - |
| bankTransactions | ✅ | - | - | - |
| billCreditNotes | ✅ | ✅ | - | ✅ |
| billPayments | ✅ | - | ✅ | - |
| bills | ✅ | ✅ | ✅ | ✅ |
| chartOfAccounts | ✅ | - | - | - |
| creditNotes | ✅ | ✅ | - | - |
| customers | ✅ | ✅ | - | - |
| directCosts | ✅ | - | ✅ | ✅ |
| directIncomes | ✅ | - | - | ✅ |
| invoices | ✅ | ✅ | ✅ | ✅ |
| items | ✅ | - | - | - |
| journalEntries | ✅ | - | ✅ | - |
| journals | ✅ | - | - | - |
| payments | ✅ | - | - | - |
| purchaseOrders | ✅ | ✅ | - | - |
| suppliers | ✅ | ✅ | - | - |
| transfers | ✅ | - | - | ✅ |
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataTypeWriteWebhook'
examples:
Record:
value:
id: bae71d36-ff47-420a-b4a6-f8c9ddf41140
eventType: '{dataType}.write.successful'
generatedDate: 2023-05-03T10:00:23.000Z
payload:
id: a9367074-b5c3-42c4-9be4-be129f43577e
type: Create
referenceCompany:
id: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
name: Toft stores
description: cust_1MtJUT2eZvKYlo2CNaw2HvEv
connectionId: 12571faf-0898-47e7-afdd-0fe9eb0a9bf5
requestedOnDate: 2023-05-03T10:00:00.000Z
completedOnDate: 2023-05-03T10:00:23.000Z
status: Success
record:
id: bil_1Nispe2eZvKYlo2Cd31jOCgZ
Attachment:
value:
id: bae71d36-ff47-420a-b4a6-f8c9ddf41140
eventType: '{dataType}.write.successful'
generatedDate: 2023-05-03T10:00:23.000Z
payload:
id: a9367074-b5c3-42c4-9be4-be129f43577e
type: UploadAttachment
referenceCompany:
id: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
name: Toft stores
description: cust_1MtJUT2eZvKYlo2CNaw2HvEv
connectionId: 12571faf-0898-47e7-afdd-0fe9eb0a9bf5
requestedOnDate: 2023-05-03T10:00:00.000Z
completedOnDate: 2023-05-03T10:00:23.000Z
status: Success
record:
id: bil_1Nispe2eZvKYlo2Cd31jOCgZ
attachmentId: att_1AZtxr2eZvKYlo2CJDX8whov
responses:
'200':
description: Return a 200 status to indicate that the webhook was received.
'{dataType}.write.unsuccessful':
post:
description: |
Indicates that a `dataType` has not been successfully created, updated, deleted, or had an attachment uploaded in the accounting software.
Codat now refers to push operations as write requests.
For example, to subscribe to events where a bill is written into the accounting software, use the `bills.write.unsuccessful` webhook.
### Supported data types and write types
| `dataType` | Create | Update | Delete | UploadAttachment |
|------------------|---------|---------|---------|------------------|
| bankAccounts | ✅ | ✅ | - | - |
| bankTransactions | ✅ | - | - | - |
| billCreditNotes | ✅ | ✅ | - | ✅ |
| billPayments | ✅ | - | ✅ | - |
| bills | ✅ | ✅ | ✅ | ✅ |
| chartOfAccounts | ✅ | - | - | - |
| creditNotes | ✅ | ✅ | - | - |
| customers | ✅ | ✅ | - | - |
| directCosts | ✅ | - | ✅ | ✅ |
| directIncomes | ✅ | - | - | ✅ |
| invoices | ✅ | ✅ | ✅ | ✅ |
| items | ✅ | - | - | - |
| journalEntries | ✅ | - | ✅ | - |
| journals | ✅ | - | - | - |
| payments | ✅ | - | - | - |
| purchaseOrders | ✅ | ✅ | - | - |
| suppliers | ✅ | ✅ | - | - |
| transfers | ✅ | - | - | ✅ |
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataTypeWriteWebhook'
examples:
Record:
value:
id: bae71d36-ff47-420a-b4a6-f8c9ddf41140
eventType: '{dataType}.write.unsuccessful'
generatedDate: 2023-05-03T10:00:23.000Z
payload:
id: a9367074-b5c3-42c4-9be4-be129f43577e
type: Update
referenceCompany:
id: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
name: Toft stores
description: cust_1MtJUT2eZvKYlo2CNaw2HvEv
connectionId: 12571faf-0898-47e7-afdd-0fe9eb0a9bf5
requestedOnDate: 2023-05-03T10:00:00.000Z
completedOnDate: 2023-05-03T10:00:23.000Z
status: Failed
Record timed out:
value:
id: bae71d36-ff47-420a-b4a6-f8c9ddf41140
eventType: '{dataType}.write.unsuccessful'
generatedDate: 2023-05-03T10:00:23.000Z
payload:
id: a9367074-b5c3-42c4-9be4-be129f43577e
type: Delete
referenceCompany:
id: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
name: Toft stores
description: cust_1MtJUT2eZvKYlo2CNaw2HvEv
connectionId: 12571faf-0898-47e7-afdd-0fe9eb0a9bf5
requestedOnDate: 2023-05-03T10:00:00.000Z
completedOnDate: 2023-05-03T10:00:23.000Z
status: TimedOut
Attachment:
value:
id: bae71d36-ff47-420a-b4a6-f8c9ddf41140
eventType: '{dataType}.write.unsuccessful'
generatedDate: 2023-05-03T10:00:23.000Z
payload:
id: a9367074-b5c3-42c4-9be4-be129f43577e
type: UploadAttachment
referenceCompany:
id: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
name: Toft stores
description: cust_1MtJUT2eZvKYlo2CNaw2HvEv
connectionId: 12571faf-0898-47e7-afdd-0fe9eb0a9bf5
requestedOnDate: 2023-05-03T10:00:00.000Z
completedOnDate: 2023-05-03T10:00:23.000Z
status: TimedOut
record:
id: bil_1Nispe2eZvKYlo2Cd31jOCgZ
responses:
'200':
description: Return a 200 status to indicate that the webhook was received.
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.
Company data connection status changed:
post:
description: Called anytime a data connection's status changes.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionStatusChangedWebhook'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
Data sync completed:
post:
deprecated: true
description: |-
Generated for each data type to indicate that data synchronization is successfully completed for that specific data type.
This event type has been deprecated. To replicate it, use the `read.completed` webhook and check if `payload.dataTypes[].status` is set to `Success` for all data types in the array.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataSyncCompletedWebhook'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
Dataset data changed:
post:
deprecated: true
description: |-
Generated for each data type to indicate that dataset synchronization has completed and updated Codat's data cache through the creation of new records or a change to existing records.
This event type has been deprecated. To replicate it, use the `read.completed` webhook and verify that `payload.dataTypes[].status` is set to `Success` and `payload.dataTypes[].modifiedRecords` is `True` for any data type in the array.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetDataChangedWebhook'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
Dataset status has changed to an error state:
post:
deprecated: true
description: |-
Indicates that the synchronization of a dataset failed.
This event type has been deprecated.
To replicate it, use the `read.completed` webhook and check if `payload.dataTypes[].status` is set to any of the following statuses for any data type in the array:
- `FetchError`
- `MapError`
- `InternalError`
- `ProcessingError`
- `ValidationError`
- `AuthError`
- `RateLimitError`
- `PermissionsError`
- `PrerequisiteNotMet`
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetStatusChangedErrorWebhook'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
New company synchronized:
post:
description: Triggered after a new company has successfully synchronized at least one dataType for the first time.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewCompanySynchronizedWebhook'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
Push operation status has changed:
post:
deprecated: true
description: |-
Indicates that a create, update, or delete operation's status has changed.
This event type has been deprecated. Use either the `{dataType}.write.successful` or `{dataType}.write.unsuccessful` instead.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PushOperationStatusChangedWebhook'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
Push operation has timed out:
post:
deprecated: true
description: |-
Indicates that a create, update, or delete operation has timed out.
This event type has been deprecated.
To replicate it, use the `{dataType}.write.unsuccessful` webhook and check if `payload.status` is set to `TimedOut`.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PushOperationTimedOutWebhook'
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:
ApiKeyDetails:
title: API key details
description: Details of the API key.
type: object
allOf:
- properties:
id:
type: string
description: Unique identifier for the API key.
example: e288a972-b402-4b21-93f9-b5335ae5679c
name:
type: string
maxLength: 50
nullable: true
description: A meaningful name assigned to the API key.
example: azure-invoice-finance-processor
apiKey:
type: string
description: The API key value used to make authenticated http requests.
example: ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd
- nullable: true
description: Datetime in UTC the API key was created. The created date will be null if the API key created before YYYY-MM-DD.
title: Created date
type: object
x-internal: true
properties:
createdDate:
$ref: '#/components/schemas/DateTime'
description: The date the entity was created.
ApiKeys:
title: API keys
x-internal: true
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ApiKeyDetails'
Branding:
title: Branding
type: object
properties:
logo:
$ref: '#/components/schemas/Branding/definitions/brandingLogo'
button:
$ref: '#/components/schemas/Branding/definitions/brandingButton'
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`.'
definitions:
brandingLogo:
description: Logo branding references.
type: object
properties:
full:
$ref: '#/components/schemas/Branding/definitions/brandingImage'
square:
$ref: '#/components/schemas/Branding/definitions/brandingImage'
brandingButton:
type: object
description: Button branding references.
properties:
default:
$ref: '#/components/schemas/Branding/definitions/brandingImage'
hover:
$ref: '#/components/schemas/Branding/definitions/brandingImage'
brandingImage:
title: Branding Image
type: object
properties:
image:
$ref: '#/components/schemas/Branding/definitions/imageReference'
examples: []
imageReference:
type: object
title: Image Reference
description: Image reference.
properties:
src:
type: string
format: uri
description: Source URL for image.
alt:
type: string
description: Alternative text when image is not available.
examples:
- logo:
full:
image:
src: 'https://static.codat.io/public/officialLogos/Full/8A156A5A-39CB-4F9D-856E-76EF9B9A9607.png'
alt: xero full icon
square:
image:
src: 'https://static.codat.io/public/officialLogos/Square/8A156A5A-39CB-4F9D-856E-76EF9B2W3607.png'
alt: xero square icon
button:
default:
image:
src: 'https://static.codat.io/public/officialButtons/Full/8A156A5A-39CB-4F9D-856E-76EF9Q7A9607.png'
alt: xero default button icon
hover:
image:
src: 'https://static.codat.io/public/officialLogos/Full/8A156A5A-39CB-4F9D-856E-76EF9B9A9607.png'
alt: xero hover button icon
sourceId: 35b92968-9851-4095-ad60-395c95cbcba4
ClientId:
title: Client ID
type: string
format: uuid
description: Unique identifier for your client in Codat.
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/ClientId'
ClientName:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/ClientName'
RuleId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/Message'
Data:
$ref: '#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData'
definitions:
ClientRateLimitReachedWebhookData:
type: object
title: Client rate limit reached webhook data
properties:
DailyQuota:
type: integer
description: The number of available requests per day.
ExpiresUtc:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC when your daily quota is reset.
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Rate Limit Reached
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: The current daily rate limit quota of 1000 requests for bae71d36-ff47-420a-b4a6-f8c9ddf41140 has been reached.
Data:
DailyQuota: 1000
ExpiresUtc: '2023-05-03T00:00:00Z'
ClientRateLimitResetWebhook:
title: Client rate limit reset webhook
x-internal: true
description: Webhook request body for a client that has had their rate limit reset.
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientId'
ClientName:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/ClientName'
RuleId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/Message'
Data:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/definitions/ClientRateLimitResetWebhookData'
definitions:
ClientRateLimitResetWebhookData:
type: object
title: Client rate limit reset webhook data
properties:
QuotaRemaining:
type: integer
description: Total number of requests remaining for your client.
nullable: true
ResetReason:
type: string
description: The reason for your rate limit quota being reset.
DailyQuota:
$ref: '#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/DailyQuota'
nullable: true
ExpiresUtc:
$ref: '#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/ExpiresUtc'
nullable: true
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Rate Limit Reset
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: The current daily rate limit quota for client 30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e has been reset to 1000 requests.
Data:
QuotaRemaining: 1000
ResetReason: The quota was reset because it is a new day.
DailyQuota: 1000
ExpiresUtc: '2023-05-03T00:00:00Z'
ClientRateLimitWebhook:
title: Client rate limit webhook
type: object
properties:
id:
type: string
format: uuid
example: 743ec94a-8aa4-44bb-8bd4-e1855ee0e74b
description: Unique identifier of the event.
eventType:
type: string
description: The type of event.
examples:
- client.rateLimit.reset
- client.rateLimit.reached
generatedDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC the event was generated in Codat.
payload:
$ref: '#/components/schemas/ClientRateLimitWebhook/definitions/clientRateLimitWebhookPayload'
definitions:
clientRateLimitWebhookPayload:
title: Client rate limit webhook payload
type: object
properties:
dailyQuota:
type: integer
description: The number of available requests per day.
quotaRemaining:
type: integer
description: Total number of requests remaining for your client.
expiryDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC when your daily quota is reset.
Companies:
title: Companies
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Company'
- $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/platform-api#/schemas/Connection) to different data sources such as one connection to [Xero](https://docs.codat.io/integrations/accounting/xero/accounting-xero) for accounting data, two connections to [Plaid](https://docs.codat.io/integrations/banking/plaid/banking-plaid) for two bank accounts and a connection to [Zettle](https://docs.codat.io/integrations/commerce/zettle/commerce-zettle) for POS data.\n\nTypically each company is one of your customers.\n\nWhen you create a company, you can specify a `name` and we will automatically generate a unique `id` for the company. You can also add a `description` to store any additional information about the company."
type: object
allOf:
- $ref: '#/components/schemas/Company/definitions/companyDetails'
- type: object
properties:
dataConnections:
type: array
items:
$ref: '#/components/schemas/Connection'
definitions:
companyDetails:
title: Company details
type: object
properties:
id:
$ref: '#/components/parameters/companyId/schema'
name:
type: string
description: The name of the company
example: Codat Ltd.
description:
$ref: '#/components/schemas/CompanyRequestBody/properties/description'
nullable: true
redirect:
type: string
format: uri
description: 'The `redirect` [Link URL](https://docs.codat.io/auth-flow/authorize-hosted-link) enabling the customer to start their auth flow journey for the company.'
example: 'https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739'
lastSync:
$ref: '#/components/schemas/DateTime'
nullable: true
created:
$ref: '#/components/schemas/DateTime'
createdByUserName:
type: string
description: Name of user that created the company in Codat.
nullable: true
products:
type: array
items:
type: string
description: An array of products that are currently enabled for the company.
tags:
type: object
maxProperties: 10
propertyNames:
pattern: '^.{1,27}$'
additional properties:
type: string
maxLength: 100
description: A collection of user-defined key-value pairs that store custom metadata against the company.
required:
- id
- name
- redirect
companyReference:
title: Company reference
type: object
properties:
id:
$ref: '#/components/parameters/companyId/schema'
name:
$ref: '#/components/schemas/Company/definitions/companyDetails/properties/name'
description:
$ref: '#/components/schemas/Company/definitions/companyDetails/properties/description'
links:
type: object
description: A collection of links for the company.
properties:
portal:
type: string
format: uri
description: Link to the company page in the portal.
tags:
$ref: '#/components/schemas/Company/definitions/companyDetails/properties/tags'
examples:
- id: 0498e921-9b53-4396-a412-4f2f5983b0a2
name: string
redirect: 'https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739'
lastSync: '2022-01-01T12:00:00.000Z'
created: '2022-01-01T12:00:00.000Z'
createdByUserName: string
tags:
region: us
uid: f6b0c253-16c7-4da1-a0c5-9c871e9c9d6c
dataConnections:
- id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd
integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c
integrationKey: dfxm
sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee
platformName: Basiq
linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: '2022-10-27T10:22:43.6464237Z'
created: '2022-10-27T09:53:29Z'
sourceType: Banking
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
CompanyWebhook:
title: Company webhook
type: object
properties:
id:
type: string
format: uuid
example: ba29118f-5406-4e59-b05c-ba307ca38d01
description: Unique identifier of the event
eventType:
type: string
description: The type of event.
examples:
- company.created
- company.deleted
generatedDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC the event was generated in Codat.
payload:
$ref: '#/components/schemas/Company/definitions/companyDetails'
Connection:
title: Connection
description: "\uFEFFA connection represents a [company's](https://docs.codat.io/platform-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:
$ref: '#/components/schemas/Branding/properties/sourceId'
sourceType:
$ref: '#/components/schemas/Integration/definitions/sourceType'
platformName:
type: string
description: Name of integration connected to company.
linkUrl:
type: string
format: uri
description: The link URL your customers can use to authorize access to their business application.
example: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/2e2eb431-c1fa-4dc9-93fa-d29781c12bcd/start'
status:
$ref: '#/components/schemas/Connection/definitions/dataConnectionStatus'
lastSync:
$ref: '#/components/schemas/DateTime'
nullable: true
created:
$ref: '#/components/schemas/DateTime'
dataConnectionErrors:
type: array
nullable: true
items:
$ref: '#/components/schemas/Connection/definitions/dataConnectionError'
connectionInfo:
type: object
nullable: true
additionalProperties:
type: string
additionalProperties: false
required:
- id
- integrationId
- integrationKey
- sourceId
- platformName
- linkUrl
- status
- created
- sourceType
definitions:
dataConnectionStatus:
title: Data connection status
description: The current authorization status of the data connection.
type: string
enum:
- PendingAuth
- Linked
- Unlinked
- Deauthorized
dataConnectionError:
title: Data connection error
type: object
properties:
statusCode:
type: string
description: The HTTP status code returned by the source platform when the error occurred.
statusText:
type: string
description: A non-numeric status code/text returned by the source platform when the error occurred.
errorMessage:
type: string
description: A message about a error returned by Codat.
erroredOnUtc:
$ref: '#/components/schemas/DateTime'
status:
title: Error status
description: The current status of a transient error. Null statuses indicate that the error is not transient.
type: string
nullable: true
enum:
- Active
- Resolved
resolvedOnUtc:
description: The datetime in Utc that the error was resolved.
nullable: true
$ref: '#/components/schemas/DateTime'
dataConnectionSourceType:
title: Source Type
description: The type of platform of the connection.
type: string
enum:
- Accounting
- Banking
- BankFeed
- Commerce
- Expense
- Other
- Unknown
example: Accounting
example:
id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd
integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c
integrationKey: dfxm
sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee
platformName: Basiq
linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start'
status: Linked
lastSync: '2022-10-27T10:22:43.6464237Z'
created: '2022-10-27T09:53:29Z'
sourceType: Banking
ConnectionManagementAccessToken:
title: Access token
type: object
properties:
accessToken:
type: string
nullable: false
description: Access token that allows SMBs to manage connections that have access to their data.
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
ConnectionManagementAllowedOrigins:
title: Allowed origins
type: object
properties:
allowedOrigins:
type: array
description: 'An array of allowed origins (i.e. your domains) to permit cross-origin resource sharing ([CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)).n resource sharing ([CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)).'
items:
type: string
format: uri
description: A domain you want to allow CORS with Codat.
example:
allowedOrigins:
- 'https://www.bank-of-dave.com'
Connections:
title: Connections
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Connection'
- $ref: '#/components/schemas/PagingInfo'
ConnectionStatusChangedWebhook:
title: Connection status changed webhook
x-internal: true
description: Webhook request body for a company's data connection status changed.
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientId'
ClientName:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/ClientName'
CompanyId:
$ref: '#/components/parameters/companyId/schema'
DataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
RuleId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/Message'
Data:
$ref: '#/components/schemas/ConnectionStatusChangedWebhook/definitions/ConnectionStatusChangedWebhookData'
definitions:
ConnectionStatusChangedWebhookData:
type: object
title: Connection status changed webhook data
properties:
dataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
newStatus:
description: The new authorization status of the data connection.
$ref: '#/components/schemas/Connection/definitions/dataConnectionStatus'
oldStatus:
description: The old authorization status of the data connection.
$ref: '#/components/schemas/Connection/definitions/dataConnectionStatus'
platformKey:
$ref: '#/components/parameters/platformKey/schema'
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
CompanyId: 8a210b68-6988-11ed-a1eb-0242ac120002
DataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: DataConnectionStatusChanged
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: Data connection for SandBox status changed from PendingAuth to Linked
Data:
dataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
newStatus: Linked
oldStatus: PendingAuth
platformKey: gbol
ConnectionWebhook:
title: Connection webhook
type: object
properties:
id:
type: string
format: uuid
example: ba29118f-5406-4e59-b05c-ba307ca38d01
description: Unique identifier of the event.
eventType:
type: string
description: The type of event.
examples:
- connection.created
- connection.connected
- connection.disconnected
- connection.reconnected
- connection.deleted
generatedDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC the event was generated in Codat.
payload:
$ref: '#/components/schemas/ConnectionWebhook/definitions/connectionWebhookPayload'
definitions:
connectionWebhookPayload:
title: Connection webhook payload
type: object
properties:
referenceCompany:
$ref: '#/components/schemas/Company/definitions/companyReference'
connection:
$ref: '#/components/schemas/Connection'
CreateApiKey:
title: Create API key
description: Details about the newly created API key.
x-internal: true
type: object
properties:
name:
$ref: '#/components/schemas/ApiKeyDetails/allOf/0/properties/name'
CustomDataTypeConfiguration:
title: Custom data type configuration
type: object
description: Client's configuration details for a specific custom data type and platform pair.
properties:
dataSource:
type: string
description: Underlying endpoint of the source platform that will serve as a data source for the custom data type. This value is not validated by Codat.
requiredData:
type: object
description: Properties required to be fetched from the underlying platform for the custom data type that is being configured. This value is not validated by Codat.
additionalProperties:
type: string
description: The client's defined name for the property with the value being the source system's property name which the mapping is targeting.
keyBy:
type: array
description: An array of properties from the source system that can be used to uniquely identify the records returned for the custom data type. This value is not validated by Codat.
items:
type: string
minLength: 1
sourceModifiedDate:
type: array
nullable: true
items:
type: string
description: Property in the source platform nominated by the client that defines the date when a record was last modified there. This value is not validated by Codat.
examples:
- dataSource: api/purchaseOrders?$filter=currencyCode eq 'NOK'
requiredData:
currencyCode: '$[*].currencyCode'
id: '$[*].id'
number: '$[*].number'
orderDate: '$[*].orderDate'
totalAmountExcludingTax: '$[*].totalAmountExcludingTax'
totalTaxAmount: '$[*].totalTaxAmount'
vendorName: '$[*].number'
keyBy:
- '$[*].id'
sourceModifiedDate:
- '$[*].lastModifiedDateTime'
CustomDataTypeRecords:
title: Custom data type records
type: object
description: Resulting records pulled from the source platform for a specific custom data type.
properties:
results:
type: array
items:
$ref: '#/components/schemas/CustomDataTypeRecords/definitions/customDataTypeRecord'
pageNumber:
$ref: '#/components/schemas/PagingInfo/properties/pageNumber'
pageSize:
$ref: '#/components/schemas/PagingInfo/properties/pageSize'
totalResults:
$ref: '#/components/schemas/PagingInfo/properties/totalResults'
definitions:
customDataTypeRecord:
title: Custom data type record
type: object
properties:
id:
type: string
nullable: false
description: Unique identifier of the record.
content:
type: object
description: Values from the source system for the properties defined in the custom data type configuration.
additionalProperties:
type: object
modifiedDate:
title: ModifiedDate
x-internal: true
type: object
properties:
modifiedDate:
allOf:
- $ref: '#/components/schemas/DateTime'
- description: |-
The date when the record was last fetched from the data source and updated in Codat’s data cache.
Use it to identify and retrieve records that have changed since your last fetch. For example, filtering `modifiedDate` to today will provide new records updated in Codat today.
This date is populated for all data types except for attachments, balance sheets, company information, and profit & loss reports ([read more](https://docs.codat.io/using-the-api/modified-dates#modified-date)).
In Codat's data model, dates and times are represented using the ISO 8601 standard.
DatasetDataChangedWebhook:
title: Dataset data changed webhook
x-internal: true
description: Webhook request body to notify that a data synchronization has completed.
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientId'
ClientName:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/ClientName'
CompanyId:
$ref: '#/components/parameters/companyId/schema'
DataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
RuleId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/Message'
Data:
title: Dataset data changed webhook data
type: object
properties:
dataType:
$ref: '#/components/schemas/DataStatus/properties/dataType'
datasetId:
$ref: '#/components/parameters/datasetId/schema'
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
CompanyId: 8a210b68-6988-11ed-a1eb-0242ac120002
DataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Dataset data changed
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: 'Data has changed for dataset type invoices, company 8a210b68-6988-11ed-a1eb-0242ac120002'
Data:
dataType: invoices
datasetId: 6586f21b-ad4d-4d06-a309-712af47184a2
DatasetStatusChangedErrorWebhook:
title: Dataset status changed to error webhook
x-internal: true
description: Webhook request body to notify that a data synchronization has completed.
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientId'
ClientName:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/ClientName'
CompanyId:
$ref: '#/components/parameters/companyId/schema'
DataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
RuleId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/Message'
Data:
$ref: '#/components/schemas/DatasetStatusChangedErrorWebhook/definitions/DatasetStatusChangedErrorWebhookData'
definitions:
DatasetStatusChangedErrorWebhookData:
type: object
title: Dataset status changed to error webhook data
properties:
dataType:
$ref: '#/components/schemas/DataStatus/properties/dataType'
datasetStatus:
type: string
description: The current status of the dataset's sync.
datasetId:
$ref: '#/components/parameters/datasetId/schema'
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
CompanyId: 8a210b68-6988-11ed-a1eb-0242ac120002
DataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Data Sync Status Changed To Error
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: 'ERROR: syncing payments triggered a ProcessingError notification at 2020-04-21T12:12:57.4250446Z.'
Data:
dataType: invoices
datasetStatus: ProcessingError
datasetId: 6586f21b-ad4d-4d06-a309-712af47184a2
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/DateTime'
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
DataStatuses:
title: Data statuses
x-internal: true
type: object
properties:
accountTransactions:
$ref: '#/components/schemas/DataStatus'
nullable: true
balanceSheet:
$ref: '#/components/schemas/DataStatus'
nullable: true
bankAccounts:
$ref: '#/components/schemas/DataStatus'
nullable: true
bankTransactions:
$ref: '#/components/schemas/DataStatus'
nullable: true
billCreditNotes:
$ref: '#/components/schemas/DataStatus'
nullable: true
billPayments:
$ref: '#/components/schemas/DataStatus'
nullable: true
bills:
$ref: '#/components/schemas/DataStatus'
nullable: true
cashFlowStatement:
$ref: '#/components/schemas/DataStatus'
nullable: true
chartOfAccounts:
$ref: '#/components/schemas/DataStatus'
nullable: true
company:
$ref: '#/components/schemas/DataStatus'
nullable: true
creditNotes:
$ref: '#/components/schemas/DataStatus'
nullable: true
customers:
$ref: '#/components/schemas/DataStatus'
nullable: true
directCosts:
$ref: '#/components/schemas/DataStatus'
nullable: true
directIncomes:
$ref: '#/components/schemas/DataStatus'
nullable: true
invoices:
$ref: '#/components/schemas/DataStatus'
nullable: true
itemReceipts:
$ref: '#/components/schemas/DataStatus'
nullable: true
items:
$ref: '#/components/schemas/DataStatus'
nullable: true
journalEntries:
$ref: '#/components/schemas/DataStatus'
nullable: true
journals:
$ref: '#/components/schemas/DataStatus'
nullable: true
paymentMethods:
$ref: '#/components/schemas/DataStatus'
nullable: true
payments:
$ref: '#/components/schemas/DataStatus'
nullable: true
profitAndLoss:
$ref: '#/components/schemas/DataStatus'
nullable: true
purchaseOrders:
$ref: '#/components/schemas/DataStatus'
nullable: true
salesOrders:
$ref: '#/components/schemas/DataStatus'
nullable: true
suppliers:
$ref: '#/components/schemas/DataStatus'
nullable: true
taxRates:
$ref: '#/components/schemas/DataStatus'
nullable: true
trackingCategories:
$ref: '#/components/schemas/DataStatus'
nullable: true
transfers:
$ref: '#/components/schemas/DataStatus'
nullable: true
banking-accountBalances:
$ref: '#/components/schemas/DataStatus'
nullable: true
banking-accounts:
$ref: '#/components/schemas/DataStatus'
nullable: true
banking-transactionCategories:
$ref: '#/components/schemas/DataStatus'
nullable: true
banking-transactions:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-companyInfo:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-customers:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-disputes:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-locations:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-orders:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-paymentMethods:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-payments:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-productCategories:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-products:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-taxComponents:
$ref: '#/components/schemas/DataStatus'
nullable: true
commerce-transactions:
$ref: '#/components/schemas/DataStatus'
nullable: true
DataSyncCompletedWebhook:
title: Data sync completed webhook
x-internal: true
description: Webhook request body to notify the completion of a data sync.
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientId'
ClientName:
type: string
description: Name of your client in Codat.
CompanyId:
$ref: '#/components/parameters/companyId/schema'
DataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
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/DataSyncCompletedWebhook/definitions/DataSyncCompletedWebhookData'
definitions:
DataSyncCompletedWebhookData:
type: object
title: Data sync completed webhook data
properties:
dataType:
$ref: '#/components/schemas/DataStatus/properties/dataType'
nullable: true
datasetId:
$ref: '#/components/parameters/datasetId/schema'
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
CompanyId: 8a210b68-6988-11ed-a1eb-0242ac120002
DataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Data sync completed
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: Data sync of type creditNotes completed for company 7626befb-0c7d-49a4-9366-bc4c81b4e4b7
Data:
dataType: creditNotes
datasetId: 1541a5ee-0d84-4b6e-a7f7-c07c1f216333
DataType:
x-internal: true
$ref: '#/components/schemas/DataStatus/properties/dataType'
DataTypeWriteWebhook:
title: Write data type webhook
type: object
properties:
id:
type: string
format: uuid
example: ba29118f-5406-4e59-b05c-ba307ca38d01
description: Unique identifier of the event.
eventType:
type: string
description: The type of event.
examples:
- bills.write.successful
- bills.write.unsuccessful
generatedDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC the event was generated in Codat.
payload:
$ref: '#/components/schemas/DataTypeWriteWebhook/definitions/dataTypeWriteWebhookPayload'
definitions:
dataTypeWriteWebhookPayload:
title: Payload
type: object
properties:
id:
type: string
description: Unique identifier of the write request. This is also known as the push operation ID.
type:
$ref: '#/components/schemas/DataTypeWriteWebhook/definitions/writeType'
referenceCompany:
$ref: '#/components/schemas/Company/definitions/companyReference'
connectionId:
$ref: '#/components/parameters/connectionId/schema'
requestedOnDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC the write request was submitted.
completedOnDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC the write request completed.
status:
$ref: '#/components/schemas/DataTypeWriteWebhook/definitions/writeStatus'
record:
$ref: '#/components/schemas/DataTypeWriteWebhook/definitions/dataTypeWriteWebhookRecord'
nullable: true
attachmentId:
type: string
nullable: true
description: 'Unique identifier for the uploaded attachment, null if no attachment uploaded.'
dataTypeWriteWebhookRecord:
type: object
properties:
id:
type: string
description: 'The unique identifier of the data type created, updated, deleted, or had an attachment uploaded in the accounting platform.'
writeType:
title: Write type
description: Type of write request.
type: string
enum:
- Create
- Update
- Delete
- UploadAttachment
writeStatus:
title: Write request status
type: string
enum:
- Pending
- Failed
- Success
- TimedOut
description: 'The current status of the write request, which is the same as the push operation status.'
DateTime:
title: Date time
type: string
examples:
- 2022-10-23T00:00:00.000Z
- 2022-10-23T00:00:00.000Z
description: |-
In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example:
```
2020-10-08T22:40:50Z
2021-01-01T00:00:00
```
When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:
- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`
- Unqualified local time: `2021-11-15T01:00:00`
- UTC time offsets: `2021-11-15T01:00:00-05:00`
> Time zones
>
> Not all dates from Codat will contain information about time zones.
> Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced.
ErrorMessage:
title: Error message
type: object
x-internal: true
properties:
statusCode:
type: integer
description: The HTTP status code returned by the error.
service:
type: string
description: Codat's service the returned the error.
error:
type: string
description: A brief description of the error.
correlationId:
type: string
description: Unique identifier used to propagate to all downstream services and determine the source of the error.
validation:
$ref: '#/components/schemas/ErrorMessage/definitions/errorValidation'
canBeRetried:
type: string
description: '`True` if the error occurred transiently and can be retried.'
detailedErrorCode:
type: integer
description: Machine readable error code used to automate processes based on the code returned.
definitions:
errorValidation:
title: Validation error
type: object
nullable: true
description: 'A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.'
properties:
errors:
type: array
nullable: true
items:
$ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem'
warnings:
type: array
nullable: true
items:
$ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem'
errorValidationItem:
title: Validation error item
type: object
properties:
itemId:
type: string
nullable: true
description: Unique identifier for a validation item.
message:
type: string
nullable: true
description: A message outlining validation item's issue.
validatorName:
type: string
nullable: true
description: Name of validator.
Integration:
title: Integration
description: An integration that Codat supports
examples:
- key: gbol
logoUrl: 'http://example.com'
name: Xero
enabled: true
sourceId: accounting
sourceType: 8193a927-ab7a-45a3-9dc2-d357a4932dfe
integrationId: 497a18ca-284e-40c0-985d-f72be35d468e
isOfflineConnector: true
isBeta: true
dataProvidedBy: string
datatypeFeatures:
- datatype: invoices
supportedFeatures:
- featureType: get
featureState: release
type: object
properties:
key:
$ref: '#/components/parameters/platformKey/schema'
logoUrl:
type: string
format: uri
description: Static url for integration's logo.
name:
type: string
example: Xero
description: Name of integration.
enabled:
type: boolean
description: Whether this integration is enabled for your customers to use.
sourceId:
$ref: '#/components/schemas/Branding/properties/sourceId'
sourceType:
$ref: '#/components/schemas/Integration/definitions/sourceType'
integrationId:
$ref: '#/components/schemas/Connection/properties/integrationId'
isOfflineConnector:
type: boolean
description: '`True` if the integration is to an application installed and run locally on an SMBs computer.'
isBeta:
type: boolean
description: '`True` if the integration is currently in beta release.'
dataProvidedBy:
type: string
description: The name of the data provider.
datatypeFeatures:
type: array
items:
$ref: '#/components/schemas/Integration/definitions/dataTypeFeature'
required:
- key
- logoUrl
- name
- enabled
definitions:
sourceType:
title: Source Type
description: The type of platform of the connection.
type: string
enum:
- Accounting
- Banking
- BankFeed
- Commerce
- Expense
- Other
- Unknown
example: Accounting
dataTypeFeature:
title: Data type feature
description: Describes support for a given datatype and associated operations
type: object
properties:
dataType:
$ref: '#/components/schemas/DataStatus/properties/dataType'
supportedFeatures:
type: array
items:
$ref: '#/components/schemas/Integration/definitions/supportedFeature'
required:
- datatype
- supportedFeatures
examples:
- datatype: invoices
supportedFeatures:
- featureType: Get
featureState: Release
supportedFeature:
type: object
x-internal: true
properties:
featureType:
$ref: '#/components/schemas/Integration/definitions/featureType'
featureState:
$ref: '#/components/schemas/Integration/definitions/featureState'
required:
- featureType
- featureState
featureState:
title: Feature state
type: string
example: Release
description: The current release state of the feature.
enum:
- Release
- Alpha
- Beta
- Deprecated
- NotSupported
- NotImplemented
featureType:
type: string
x-internal: true
description: The type of feature.
enum:
- Get
- Post
- Categorization
- Delete
- Put
- GetAsPdf
- DownloadAttachment
- GetAttachment
- GetAttachments
- UploadAttachment
example: Get
Integrations:
title: Integrations
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Integration'
- $ref: '#/components/schemas/PagingInfo'
NewCompanySynchronizedWebhook:
title: New company synchronized webhook
x-internal: true
description: Webhook request body to notify that a new company has successfully synchronized at least one dataType for the first time.
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientId'
ClientName:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/ClientName'
CompanyId:
$ref: '#/components/parameters/companyId/schema'
DataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
RuleId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/Message'
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
CompanyId: 8a210b68-6988-11ed-a1eb-0242ac120002
DataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: New company synchronised
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: Company 8a210b68-6988-11ed-a1eb-0242ac120002 synced for the first time
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'
Profile:
title: Profile
description: Describes your Codat client instance
examples:
- name: Bob's Burgers
logoUrl: 'https://client-images.codat.io/logo/042399f5-d104-4f38-9ce8-cac3524f4e88_5806cb1f-7342-4c0e-a0a8-99bfbc47b0ff.png'
iconUrl: 'https://client-images.codat.io/icon/042399f5-d104-4f38-9ce8-cac3524f4e88_3f5623af-d992-4c22-bc08-e58c520a8526.ico'
redirectUrl: 'https://bobs-burgers.{countrySuffix}/{companyId}'
whiteListUrls:
- 'https://bobs-burgers.com'
- 'https://bobs-burgers.co.uk'
confirmCompanyName: true
type: object
properties:
name:
type: string
example: Bob's Burgers
description: The name given to the instance.
logoUrl:
type: string
description: Static url to your organization's logo.
example: 'https://client-images.codat.io/logo/042399f5-d104-4f38-9ce8-cac3524f4e88_5806cb1f-7342-4c0e-a0a8-99bfbc47b0ff.png'
iconUrl:
type: string
description: Static url to your organization's icon.
example: 'https://client-images.codat.io/icon/042399f5-d104-4f38-9ce8-cac3524f4e88_3f5623af-d992-4c22-bc08-e58c520a8526.ico'
redirectUrl:
type: string
example: 'https://bobs-burgers.{countrySuffix}/{companyId}'
description: 'The redirect URL pasted on to the SMB once Codat''s [Hosted Link](https://docs.codat.io/auth-flow/authorize-hosted-link) has been completed by the SMB.'
whiteListUrls:
type: array
description: A list of urls that are allowed to communicate with Codat. If empty any url is allowed to communicate with Codat.
items:
type: string
format: uri
example: 'https://bobs-burgers.com'
description: A url that is allowed to communicate with Codat.
apiKey:
type: string
deprecated: true
example: sartANTjHAkLdbyDfaynoTQb7pkmj6hXHmnQKMrB
description: The API key for this Codat instance.
alertAuthHeader:
type: string
example: Bearer tXEiHiRK7XCtI8TNHbpGs1LI1pumdb4Cl1QIo7B2
description: Alert or webhooks authorization header.
confirmCompanyName:
type: boolean
deprecated: true
description: '`True` if the company name has been confirmed.'
required:
- name
- redirectUrl
x-stoplight:
id: b1fyq05edangf
PullOperation:
title: Pull operation
description: |-
Information about a queued, in progress or completed pull operation.
*Formally called `dataset`*
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the pull operation.
example: 943accd0-4247-42d8-865b-363c8629e1da
companyId:
type: string
format: uuid
description: Unique identifier of the company associated to this pull operation.
example: 22ece347-e5f6-4896-95e0-35a4c7f17023
connectionId:
type: string
format: uuid
description: Unique identifier of the connection associated to this pull operation.
example: 50830828-7d39-4367-b0eb-5ddb2de5faa5
dataType:
title: Data types
x-internal: true
type: string
description: The data type you are requesting in a pull operation.
status:
title: Dataset status
type: string
description: The current status of the dataset.
enum:
- Initial
- Queued
- Fetching
- MapQueued
- Mapping
- Complete
- FetchError
- MapError
- InternalError
- ProcessingQueued
- Processing
- ProcessingError
- ValidationQueued
- Validating
- ValidationError
- AuthError
- Cancelled
- NotSupported
- RateLimitError
- PermissionsError
- PrerequisiteNotMet
statusDescription:
type: string
nullable: true
description: Additional information about the dataset status.
example: 'Paused until 2022-10-23T00:00:00.000Z'
errorMessage:
type: string
nullable: true
description: A message about a transient or persistent error returned by Codat or the source platform.
requested:
$ref: '#/components/schemas/DateTime'
completed:
$ref: '#/components/schemas/DateTime'
progress:
type: integer
description: An integer signifying the progress of the pull operation.
isCompleted:
type: boolean
description: '`True` if the pull operation is completed successfully. The `isCompleted` property is not queryable. To filter failed pull operations, query by `status!=Complete&&status!=NotSupported` instead.'
isErrored:
type: boolean
description: '`True` if the pull operation entered an error state.'
required:
- id
- companyId
- connectionId
- dataType
- status
- requested
- progress
- isCompleted
- isErrored
examples:
- id: 97d60846-f07a-4d42-b5a0-0bdcc6ebf56b
companyId: 4645bd78-8988-45bc-ac9e-67ba5df6e4e5
connectionId: 51baa045-4836-4317-a42e-3542e991e581
dataType: invoices
status: Initial
statusDescription: 'Paused until 2022-10-23T00:00:00.000Z'
requested: '2022-11-14T11:18:37.2798351Z'
progress: 10
isCompleted: false
isErrored: false
PullOperations:
title: Pull operations
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/PullOperation'
- $ref: '#/components/schemas/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/DateTime'
description: The datetime when the push was requested.
completedOnUtc:
$ref: '#/components/schemas/DateTime'
description: 'The datetime when the push was completed, null if Pending.'
timeoutInMinutes:
type: integer
format: int32
nullable: true
description: Number of minutes the push operation must complete within before it times out.
timeoutInSeconds:
type: integer
format: int32
nullable: true
deprecated: true
description: Number of seconds the push operation must complete within before it times out.
status:
$ref: '#/components/schemas/PushOperation/definitions/pushOperationStatus'
errorMessage:
type: string
nullable: true
description: A message about the error.
validation:
$ref: '#/components/schemas/PushOperation/definitions/validation'
statusCode:
type: integer
description: Push status code.
required:
- companyId
- pushOperationKey
- dataConnectionKey
- requestedOnUtc
- status
- statusCode
definitions:
validation:
type: object
title: Validation
description: 'A human-readable object describing validation decisions Codat has made when pushing data into the platform. If a push has failed because of validation errors, they will be detailed here.'
properties:
errors:
type: array
nullable: true
items:
$ref: '#/components/schemas/PushOperation/definitions/validationItem'
warnings:
type: array
nullable: true
items:
$ref: '#/components/schemas/PushOperation/definitions/validationItem'
validationItem:
title: Validation item
type: object
properties:
itemId:
type: string
nullable: true
description: Unique identifier for a validation item.
message:
type: string
nullable: true
description: A message outlining validation item's issue.
validatorName:
type: string
nullable: true
description: Name of validator.
additionalProperties: false
pushChangeType:
title: Push change type
description: Type of change being applied to record in third party platform.
type: string
enum:
- Unknown
- Created
- Modified
- Deleted
- AttachmentUploaded
pushOperationRef:
title: Push operation reference
x-internal: true
type: object
properties:
id:
type: string
description: Unique identifier for a push operation.
dataType:
$ref: '#/components/schemas/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'
PushOperationStatusChangedWebhook:
title: Push operation status changed webhook
x-internal: true
description: Webhook request body for a push operation status change.
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientId'
ClientName:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/ClientName'
CompanyId:
$ref: '#/components/parameters/companyId/schema'
DataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
RuleId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/Message'
Data:
$ref: '#/components/schemas/PushOperationStatusChangedWebhook/definitions/PushOperationStatusChangedWebhookData'
definitions:
PushOperationStatusChangedWebhookData:
type: object
title: Push operation status changed webhook data
properties:
dataType:
$ref: '#/components/schemas/DataStatus/properties/dataType'
status:
$ref: '#/components/schemas/PushOperation/definitions/pushOperationStatus'
pushOperationKey:
$ref: '#/components/schemas/PushOperation/properties/pushOperationKey'
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
CompanyId: 8a210b68-6988-11ed-a1eb-0242ac120002
DataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Push Operation Status Changed()
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: 'invoices triggered notification for PushOperationStatusChanged at 2019-05-22T18:19:42.742Z'
Data:
dataType: invoices
status: Success
pushOperationKey: c2f8847d-3047-4619-a157-6d947d8e4a73
PushOperationTimedOutWebhook:
title: Push operation timed out webhook
x-internal: true
description: Webhook request body notifying that a push push operation has timed out.
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientId'
ClientName:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/ClientName'
CompanyId:
$ref: '#/components/parameters/companyId/schema'
DataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
RuleId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/DataSyncCompletedWebhook/properties/Message'
Data:
$ref: '#/components/schemas/PushOperationTimedOutWebhook/definitions/PushOperationTimedOutWebhookData'
definitions:
PushOperationTimedOutWebhookData:
type: object
title: Push operation timed out webhook data
properties:
dataType:
$ref: '#/components/schemas/DataStatus/properties/dataType'
pushOperationKey:
$ref: '#/components/schemas/PushOperation/properties/pushOperationKey'
pushOperationGuid:
$ref: '#/components/schemas/PushOperation/properties/pushOperationKey'
deprecated: true
x-speakeasy-deprecation-replacement: pushOperationKey
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
CompanyId: 8a210b68-6988-11ed-a1eb-0242ac120002
DataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Push Operation Timed Out
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: 'ERROR: pushing invoices never finished in time, timing out at 2020-09-07T08:42:13'
Data:
dataType: invoices
pushOperationKey: c2f8847d-3047-4619-a157-6d947d8e4a73
pushOperationGuid: c2f8847d-3047-4619-a157-6d947d8e4a73
PushOption:
title: Push option
x-internal: true
required:
- displayName
- required
- type
type: object
properties:
type:
$ref: '#/components/schemas/PushOption/definitions/pushOptionType'
displayName:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/displayName'
description:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/description'
required:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/required'
properties:
type: object
additionalProperties:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty'
nullable: true
options:
type: array
items:
$ref: '#/components/schemas/PushOption/definitions/pushOptionChoice'
nullable: true
validation:
$ref: '#/components/schemas/PushOption/definitions/pushValidationInfo'
nullable: true
definitions:
pushOptionProperty:
title: Push Option Property
required:
- description
- displayName
- required
- type
type: object
properties:
type:
$ref: '#/components/schemas/PushOption/definitions/pushOptionType'
displayName:
minLength: 1
type: string
description: The property's display name.
description:
type: string
description: A description of the property.
required:
type: boolean
description: The property is required if `True`.
properties:
type: object
additionalProperties:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty'
nullable: true
options:
type: array
items:
$ref: '#/components/schemas/PushOption/definitions/pushOptionChoice'
nullable: true
validation:
$ref: '#/components/schemas/PushOption/definitions/pushValidationInfo'
pushValidationInfo:
title: Push validation info
type: object
properties:
warnings:
type: array
items:
$ref: '#/components/schemas/PushOption/definitions/pushFieldValidation'
nullable: true
information:
type: array
items:
$ref: '#/components/schemas/PushOption/definitions/pushFieldValidation'
nullable: true
additionalProperties: false
pushFieldValidation:
title: Push field validation
required:
- details
type: object
properties:
field:
type: string
description: Field name that resulted in the validation issue.
details:
minLength: 1
type: string
description: Details on the validation issue.
ref:
type: string
format: uri
nullable: true
description: Unique reference identifier for the validation issue.
additionalProperties: false
pushOptionType:
title: Option Type
description: The option type.
enum:
- Array
- Object
- String
- Number
- Boolean
- DateTime
- File
- MultiPart
type: string
pushOptionChoice:
title: Push Option Choice
type: object
properties:
value:
type: string
minLength: 1
description: Allowed value for field.
type:
$ref: '#/components/schemas/PushOption/definitions/pushOptionType'
displayName:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/displayName'
description:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/description'
required:
$ref: '#/components/schemas/PushOption/definitions/pushOptionProperty/properties/required'
ReadCompletedWebhook:
title: Read completed 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.
generatedDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC the event was generated in Codat.
payload:
$ref: '#/components/schemas/ReadCompletedWebhook/definitions/readCompletedWebhookPayload'
definitions:
readCompletedWebhookPayload:
title: Company fetch completed webhook payload
type: object
properties:
referenceCompany:
$ref: '#/components/schemas/Company/definitions/companyReference'
modifiedFromDate:
$ref: '#/components/schemas/DateTime'
description: The date time in UTC when the data types were last fetched and input into Codat's cache.
nullable: true
dataTypes:
type: array
items:
type: object
properties:
connectionId:
$ref: '#/components/parameters/connectionId/schema'
dataType:
$ref: '#/components/schemas/DataStatus/properties/dataType'
recordsModified:
type: boolean
example: false
description: '`True` if records have been created, updated or deleted in Codat''s cache.'
status:
$ref: '#/components/schemas/PullOperation/properties/status'
SupplementalDataConfiguration:
description: ''
title: Supplemental data configuration
type: object
properties:
supplementalDataConfig:
type: object
additionalProperties:
type: object
title: Supplemental data source configuration
description: The client's defined name for the object.
properties:
dataSource:
type: string
description: 'The underlying endpoint of the source system which the configuration is targeting. '
pullData:
type: object
description: The additional properties that are required when pulling records.
additionalProperties:
type: string
description: The client's defined name for the property with the value being the source system's property name which the mapping is targeting.
pushData:
type: object
description: The additional properties that are required to create and/or update records.
additionalProperties:
type: string
description: The client's defined name for the property with the value being the source system's property name which the mapping is targeting.
examples:
- supplementalDataConfig:
orders-supplemental-data:
dataSource: /orders
pullData:
orderNumber: order_num
pushData:
orderNumber: order_num
SyncSetting:
title: SyncSetting
description: 'Describes how often, and how much history, should be fetched for the given data type when a pull operation is queued.'
examples:
- dataType: invoices
fetchOnFirstLink: true
syncSchedule: 24
syncOrder: 0
syncFromUtc: '2020-01-01T12:00:00.000Z'
syncFromWindow: 24
monthsToSync: 24
isLocked: true
type: object
properties:
dataType:
$ref: '#/components/schemas/DataStatus/properties/dataType'
fetchOnFirstLink:
type: boolean
description: Whether this data type should be queued after a company has authorized a connection.
syncSchedule:
type: integer
example: 24
description: Number of hours after which this data type should be refreshed.
syncOrder:
type: integer
description: The sync in which data types are queued for a sync.
syncFromUtc:
$ref: '#/components/schemas/DateTime'
description: Date from which data should be fetched. Set this *or* `syncFromWindow`.
syncFromWindow:
type: integer
example: 24
description: Number of months of data to be fetched. Set this *or* `syncFromUTC`.
monthsToSync:
type: integer
example: 24
description: 'Months of data to fetch, for report data types (`balanceSheet` & `profitAndLoss`) only.'
isLocked:
type: boolean
description: '`True` if the [sync setting](https://docs.codat.io/knowledge-base/advanced-sync-settings) is locked.'
required:
- dataType
- fetchOnFirstLink
- syncSchedule
- syncOrder
SyncSettings:
title: Sync settings
x-internal: true
type: object
properties:
clientId:
$ref: '#/components/schemas/ClientId'
settings:
type: array
items:
$ref: '#/components/schemas/SyncSetting'
overridesDefaults:
type: boolean
description: 'Set to `True` if you want to override the default [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings).'
UpdateConnectionStatus:
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
Webhook:
title: Webhook
description: Configuration to provide an event notification to a URL or list of email addresses based on the given type or condition.
type: object
allOf:
- type: object
properties:
id:
type: string
format: uuid
nullable: false
description: Unique identifier for the configured notification.
example: ff89c50e-a719-4ef5-a182-9917e53927b6
- $ref: '#/components/schemas/Webhook/definitions/createRule'
definitions:
createRule:
title: Create webhook
description: Create a message that notifies a URL of an event based on its given type or condition.
type: object
properties:
type:
type: string
description: The type of webhook.
companyId:
$ref: '#/components/parameters/companyId/schema'
notifiers:
$ref: '#/components/schemas/Webhook/definitions/webhookNotifier'
examples:
- type: DataConnectionStatusChanged
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
required:
- type
- notifiers
webhookNotifier:
type: object
title: Webhook notifiers
properties:
emails:
type: array
items:
type: string
format: email
description: Receiver's email address.
example: info@client.com
webhook:
type: string
format: uri
description: The URI the webhook service will use to post events.
example: 'https://webhook.client.com'
webhooks:
title: Webhooks
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Webhook'
- $ref: '#/components/schemas/PagingInfo'
examples:
- id: ff89c50e-a719-4ef5-a182-9917e53927b6
type: DataConnectionStatusChanged
companyId: 39b73b17-cc2e-429e-915d-71654e9dcd1e
notifiers:
emails:
- info@client.com
webhook: 'https://webhook.client.com'
WebhookConsumer:
title: Webhook consumer
type: object
description: "\uFEFFA webhook consumer is an HTTP endpoint that developers can configure to subscribe to Codat's supported event types.\n\nSee our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview).\n"
properties:
id:
type: string
format: uuid
example: 8a210b68-6988-11ed-a1eb-0242ac120002
description: Unique identifier for the webhook consumer.
url:
type: string
format: uri
description: The URL that will consume webhook events dispatched by Codat.
disabled:
type: boolean
description: Flag that enables or disables the endpoint from receiving events. Disabled when set to `true`.
nullable: true
default: false
eventTypes:
type: array
description: An array of event types the webhook consumer subscribes to.
items:
type: string
companyTags:
type: array
description: 'Company tags provide an additional way to filter messages, independent of event types. Company tags are case-sensitive, and only messages from companies with matching tags will be sent to this endpoint. Use the format `tagKey:tagValue`.'
items:
type: string
maxLength: 128
maxItems: 10
companyId:
deprecated: true
type: string
format: uuid
nullable: true
example: 8a210b68-6988-11ed-a1eb-0242ac120002
description: Unique identifier of the company to indicate company-specific events. The associated webhook consumer will receive events only for the specified ID.
definitions:
webhookConsumerPrototype:
title: Create webhook consumer
type: object
properties:
url:
$ref: '#/components/schemas/WebhookConsumer/properties/url'
disabled:
$ref: '#/components/schemas/WebhookConsumer/properties/disabled'
eventTypes:
$ref: '#/components/schemas/WebhookConsumer/properties/eventTypes'
companyTags:
$ref: '#/components/schemas/WebhookConsumer/properties/companyTags'
companyId:
$ref: '#/components/schemas/WebhookConsumer/properties/companyId'
webhookConsumers:
title: Webhook consumers
type: object
properties:
results:
type: array
maxItems: 50
items:
$ref: '#/components/schemas/WebhookConsumer'
WebhookZapierKey:
title: Zapier integration key
type: object
properties:
key:
type: string
description: Integration key used to authorize Zapier's HTTP requests with Codat.
example: sk_integ_WM4dfoK1nKZnDE_kceze6hWDjbRwOZwG.us
examples:
- key: sk_integ_WM4dfoK1nKZnDE_kceze6hWDjbRwOZwG.us
responses:
Bad-Request:
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
ConnectionManagementAllowedOrigins:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionManagementAllowedOrigins'
examples:
Allowed origins:
$ref: '#/components/examples/connectionManagementAllowedOriginsResponse'
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
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
Legal-Reasons:
description: Not currently available due to compliance limitations. Reach out to your Codat contact for further assistance.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Conflict:
value:
statusCode: 451
service: StdznCustomData
error: Platform 'qudb' is not currently available for compliance purposes.
correlationId: f63017dabb9b87865573bea95a51e55d
canBeRetried: Unknown
detailedErrorCode: 0
Internal-Server-Error:
description: There is a problem with our server. Please try again later.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Conflict:
value:
statusCode: 500
service: PublicApi
error: There is a problem with our server. Please try again later.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
Service-Unavailable:
description: The Codat API is temporarily offline for maintenance. Please try again later.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Conflict:
value:
statusCode: 500
service: PublicApi
error: The Codat API is temporarily offline for maintenance. Please try again later.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
parameters:
companyId:
name: companyId
in: path
required: true
schema:
type: string
format: uuid
example: 8a210b68-6988-11ed-a1eb-0242ac120002
description: Unique identifier for your SMB in Codat.
description: Unique identifier for a company.
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.
customDataIdentifier:
name: customDataIdentifier
in: path
required: true
schema:
type: string
example: DynamicsPurchaseOrders
description: Unique identifier for a custom data type.
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).'
productIdentifier:
name: productIdentifier
in: path
required: true
schema:
type: string
examples:
- bank-feeds
- lending
- payables
- expenses
description: Human-readable product identifier for a product.
query:
name: query
in: query
required: false
schema:
type: string
example: id=e3334455-1aed-4e71-ab43-6bccf12092ee
description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).'
orderBy:
name: orderBy
in: query
required: false
schema:
type: string
example: '-modifiedDate'
description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).'
dataType:
name: dataType
description: The key of a Codat data type.
in: path
required: true
schema:
$ref: '#/components/schemas/DataType'
ruleId:
name: ruleId
in: path
required: true
schema:
type: string
format: uuid
example: 7318949f-c008-4936-a8ff-10d7ab563fa6
description: Unique ID of the webhook or rule.
datasetId:
name: datasetId
in: path
required: true
schema:
type: string
format: uuid
description: Unique identifier for the dataset that completed its sync.
description: Unique identifier for the dataset that completed its sync.
platformKey:
name: platformKey
in: path
required: true
schema:
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.'
description: A unique 4-letter key to represent a platform in each integration.
webhookId:
name: webhookId
in: path
required: true
schema:
$ref: '#/components/schemas/WebhookConsumer/properties/id'
description: Unique identifier for the webhook consumer.
examples:
connectionManagementAllowedOriginsResponse:
value:
allowedOrigins:
- 'https://www.bank-of-dave.com'
securitySchemes:
auth_header:
name: Authorization
description: 'The word "Basic" followed by a space and your API key. [API keys](https://docs.codat.io/platform-api#/schemas/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)