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: Connection management description: Configure UI and retrieve access tokens for authentication used by **Connections SDK**. - name: Connections description: Create new and manage existing data connections for a company. - 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: Read data description: View validation outcomes for completed read data 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 products: - spend-insights - lending - expenses-v1 - commerce referenceSubsidiaryCompanies: [] 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 products: - spend-insights - lending - payables-v2 referenceSubsidiaryCompanies: [] - id: ab12c58d-a678-4ebf-a159-ae99e1807bd0 name: Toft stores redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0' dataConnections: [] created: '2022-11-10T10:45:18Z' createdByUserName: Dan Tzabar products: - spend-insights referenceSubsidiaryCompanies: - id: c8d3af58-7011-47ce-b3f2-89faf300ef6d name: Toft stores UK links: portal: 'https://app.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/summary' - id: db94eddc-9212-4568-9b5c-3eab0e325913 name: Toft stores US links: portal: 'https://app.codat.io/companies/db94eddc-9212-4568-9b5c-3eab0e325913/summary' - id: c8d3af58-7011-47ce-b3f2-89faf300ef6d name: Toft stores UK redirect: 'https://link.codat.io/company/c8d3af58-7011-47ce-b3f2-89faf300ef6d' dataConnections: - id: d5ab61b7-1ad0-46fd-9f9f-b6761047941e integrationId: cc750323-5a47-4f28-8d8e-30fbbf2ce137 integrationKey: akxx sourceId: 9815b998-024d-4415-a40b-89903b2cad6f platformName: Oracle NetSuite linkUrl: 'https://link-api.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/connections/d5ab61b7-1ad0-46fd-9f9f-b6761047941e/start' status: Linked lastSync: '2022-01-01T12:30:00.000Z' created: '2022-01-01T11:30:00Z' sourceType: Accounting created: '2022-11-10T10:45:18Z' createdByUserName: Dan Tzabar products: - lending - spend-insights - payables referenceParentCompany: id: ab12c58d-a678-4ebf-a159-ae99e1807bd0 name: Toft stores links: portal: 'https://app.codat.io/companies/ab12c58d-a678-4ebf-a159-ae99e1807bd0/summary' referenceSubsidiaryCompanies: [] - id: db94eddc-9212-4568-9b5c-3eab0e325913 name: Toft stores US redirect: 'https://link.codat.io/company/db94eddc-9212-4568-9b5c-3eab0e325913' dataConnections: - id: 1e5c8c9e-27fd-4ba9-9a2a-d02ba65bc2fb integrationId: cc750323-5a47-4f28-8d8e-30fbbf2ce137 integrationKey: akxx sourceId: 9815b998-024d-4415-a40b-89903b2cad6f platformName: Oracle NetSuite linkUrl: 'https://link-api.codat.io/companies/db94eddc-9212-4568-9b5c-3eab0e325913/connections/1e5c8c9e-27fd-4ba9-9a2a-d02ba65bc2fb/start' status: Linked lastSync: '2022-01-01T12:30:00.000Z' created: '2022-01-01T11:30:00Z' sourceType: Accounting created: '2022-11-10T10:45:18Z' createdByUserName: Dan Tzabar products: - spend-insights referenceParentCompany: id: ab12c58d-a678-4ebf-a159-ae99e1807bd0 name: Toft stores links: portal: 'https://app.codat.io/companies/ab12c58d-a678-4ebf-a159-ae99e1807bd0/summary' referenceSubsidiaryCompanies: [] pageNumber: 1 pageSize: 100 totalResults: 3 _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](https://docs.codat.io/platform-api#/schemas/Company) 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.\n\n## Filter by tags\n\nThe *List companies* endpoint supports the filtering of companies using [tags](https://docs.codat.io/using-the-api/managing-companies#add-metadata-to-a-company). It supports the following operators with [Codat’s query language](https://docs.codat.io/using-the-api/querying):\n\n- equals (`=`)\n- not equals (`!=`)\n- contains (`~`)\n\nFor example, you can use the querying to filter companies tagged with a specific foreign key, region, or owning team: \n- Foreign key: `uid = {yourCustomerId}`\n- Region: `region != uk`\n- Owning team and region: `region = uk && owningTeam = invoice-finance`" parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/orderBy' - name: tags in: query schema: type: string example: region=uk && team=invoice-finance description: 'Filter companies by tags using the "equals" (=), "not equals" (!=), and "contains" (~) operators with [Codat’s query language](https://docs.codat.io/using-the-api/querying).' 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 products: - spend-insights referenceSubsidiaryCompanies: [] 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 products: - spend-insights referenceSubsidiaryCompanies: [] 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 products: - spend-insights tags: region: us referenceSubsidiaryCompanies: [] '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: Toft stores holdings description: '' platform: '' redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0' dataConnections: [] created: '2022-11-10T10:45:18Z' createdByUserName: Dan Tzabar products: - spend-insights - lending - expenses-v1 - commerce referenceSubsidiaryCompanies: [] Parent multi-entity company: value: id: ab12c58d-a678-4ebf-a159-ae99e1807bd0 name: Toft stores description: '' platform: '' redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0' dataConnections: [] created: '2022-11-10T10:45:18Z' createdByUserName: Dan Tzabar products: - spend-insights - lending - expenses-v1 - commerce referenceSubsidiaryCompanies: - id: c8d3af58-7011-47ce-b3f2-89faf300ef6d name: Toft stores UK links: portal: 'https://app.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/summary' - id: db94eddc-9212-4568-9b5c-3eab0e325913 name: Toft stores US links: portal: 'https://app.codat.io/companies/db94eddc-9212-4568-9b5c-3eab0e325913/summary' Subsidiary multi-entity company: value: id: c8d3af58-7011-47ce-b3f2-89faf300ef6d name: Toft stores UK description: '' platform: '' redirect: 'https://link.codat.io/company/c8d3af58-7011-47ce-b3f2-89faf300ef6d' dataConnections: - id: d5ab61b7-1ad0-46fd-9f9f-b6761047941e integrationId: cc750323-5a47-4f28-8d8e-30fbbf2ce137 integrationKey: akxx sourceId: 9815b998-024d-4415-a40b-89903b2cad6f platformName: Oracle NetSuite linkUrl: 'https://link-api.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/connections/d5ab61b7-1ad0-46fd-9f9f-b6761047941e/start' status: Linked lastSync: '2022-01-01T12:30:00.000Z' created: '2022-01-01T11:30:00Z' sourceType: Accounting created: '2022-11-10T10:45:18Z' createdByUserName: Dan Tzabar products: - spend-insights - lending - expenses-v1 - commerce referenceParentCompany: id: ab12c58d-a678-4ebf-a159-ae99e1807bd0 name: Toft stores links: portal: 'https://app.codat.io/companies/ab12c58d-a678-4ebf-a159-ae99e1807bd0/summary' referenceSubsidiaryCompanies: [] '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: Replace company description: "\uFEFFUse the *Replace company* endpoint to replace the existing name, description, and tags of the company. Calling the endpoint will replace existing values even if new values haven't been defined in the payload.\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: replace-company x-speakeasy-name-override: replace 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 patch: summary: Update company description: "\uFEFFUse the *Update company* endpoint to update the name, description, or tags of the company.\n\nThe *Update company* endpoint doesn't have any required fields. If any of the fields provided are `null` or not provided, they won't be included in the update. \n\nA [company](https://docs.codat.io/platform-api#/schemas/Company) represents a business sharing access to their 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/CompanyUpdateRequest' examples: Update tags: value: tags: refrence: new reference Update name: value: name: New Name '/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}/products/{productIdentifier}/refresh': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/productIdentifier' post: summary: Refresh product data operationId: refresh-product-data x-speakeasy-name-override: refresh-product-data description: |- Use the **Refresh product data** endpoint to manually refresh data for a custom product for a specific company. ### Tips and traps - This endpoint only supports refreshing data for **custom products** and can't be used for Codat's standard solutions. Refer to [individual solutions' documentation](https://docs.codat.io/) instead. - If a data sync is already in progress for a custom product, the refresh request will return a `Bad request (400)` response. - If a company has multiple custom products enabled, you can refresh data for each product individually. - Optionally include a request body with `dataTypes` to refresh only selected data types for the specified product. If omitted, the product's scheduled refresh is triggered as usual. - When specifying `dataTypes`, each value must be a valid data type supported by the product. Invalid values will result in a `Bad request (400)` response listing valid options. tags: - Companies requestBody: required: false description: 'Optionally specify one or more data types to refresh for the given custom product. If omitted, the product''s scheduled refresh is triggered as usual. When provided, each data type must be valid for the specified product.' content: application/json: schema: type: object properties: dataTypes: type: array description: One or more data types to refresh for the product. items: type: string additionalProperties: false examples: Filter specific data types: value: dataTypes: - invoices - payments responses: '202': description: OK '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Standard product not supported: value: statusCode: 400 service: PublicApi error: 'Bank Feeds doesn''t support data refreshing. For more information, refer to your solution’s documentation [here](https://docs.codat.io).' correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Read in progress: value: statusCode: 400 service: PublicApi error: Data cannot be refreshed while a read operation is in progress. Allow the read to complete before attempting to refresh. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 '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}/accessToken': get: summary: Get company access token operationId: get-company-access-token x-speakeasy-name-override: get-access-token description: |- Use the _Get company access token_ endpoint to return an access token for the specified company ID. The token is valid for one day. The token is required by Codat's embeddable UIs (such as [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) and [Link SDK](https://docs.codat.io/auth-flow/authorize-embedded-link)) to verify the identity of the user and improve the reliability of data provided by them. parameters: - $ref: '#/components/parameters/companyId' tags: - Companies responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CompanyAccessToken' examples: Simple company: value: expiresIn: 86400 accessToken: string tokenType: Bearer '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}/connectionManagement/accessToken': parameters: - $ref: '#/components/parameters/companyId' get: summary: Get access token (old) operationId: get-connection-management-access-token deprecated: true x-speakeasy-deprecation-message: | The endpoint for generating company-specific connection management access tokens has been deprecated. Codat now supports a global company access token, providing seamless access across multiple products. Update your integration to use the global token for improved efficiency and consistency. x-speakeasy-deprecation-replacement: get-company-access-token tags: - Connection management description: "\uFEFFThe new [Get company access token](https://docs.codat.io/platform-api#/operations/get-company-access-token) endpoint replaces this endpoint and includes additional functionality." 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 (old) operationId: get-connection-management-cors-settings x-speakeasy-group: cors deprecated: true x-speakeasy-deprecation-message: | The new [Get CORS settings](https://docs.codat.io/platform-api#/operations/get-cors-settings) endpoint replaces this endpoint and includes additional functionality. Update your integrations to use the new path `/corsSettings` as the existing route will be removed in a future release. x-speakeasy-deprecation-replacement: get-cors-settings tags: - Settings 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 UIs (such as [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) and [Link SDK](https://docs.codat.io/auth-flow/authorize-embedded-link)) to access Codat's API endpoints." 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 (old) operationId: set-connection-management-cors-settings x-speakeasy-name-override: set x-speakeasy-group: cors deprecated: true x-speakeasy-deprecation-message: | The new [Set CORS settings](https://docs.codat.io/platform-api#/operations/set-cors-settings) endpoint replaces this endpoint and includes additional functionality. Update your integrations to use the new path `/corsSettings` as the existing route will be removed in a future release. x-speakeasy-deprecation-replacement: set-cors-settings tags: - Settings 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 UIs (such as [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) and [Link SDK](https://docs.codat.io/auth-flow/authorize-embedded-link)) to access Codat's API endpoints. " 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' /corsSettings: get: summary: Get CORS settings operationId: get-cors-settings tags: - Settings 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 UIs (such as [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) and [Link SDK](https://docs.codat.io/auth-flow/authorize-embedded-link)) to access Codat's API endpoints." 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-cors-settings x-speakeasy-name-override: set tags: - Settings 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 UIs (such as [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) and [Link SDK](https://docs.codat.io/auth-flow/authorize-embedded-link)) to access Codat's API endpoints." 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 '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: |- 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' '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}/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. /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}/sync/{datasetId}/validation': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/datasetId' get: summary: Get validation results tags: - Read data operationId: get-read-validation-results x-speakeasy-name-override: get-validation-results description: |- Use the **Get validation results** endpoint to review warnings and errors encountered during the data type validation phase. The validation result [schema](https://docs.codat.io/platform-api#/schemas/ValidationResult) contains two message arrays: - **`warnings`** array lists potential issues with the data type that may require attention but don't block usage. - **`errors`** array contains critical issues that must be resolved before the data type can be used. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ValidationResult' examples: Validation result: value: errors: - ruleId: accounting-bill-030 itemId: fc2f2d1a-ff4d-40c6-a7fb-4bd7d04f4008 message: A bill's lines summed (69.99) should be the same as TotalAmount (70.00). validatorName: BillValidator warnings: - ruleId: accounting-bill-032 itemId: 1d3979e5-7c28-432e-b562-04e9013c1ea0 message: A bill's lines sub total amount summed (3201.20) should be the same as SubTotal (3201.25) validatorName: BillValidator '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. '/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/supplemental-data/overview) is additional data you can include in Codat's standard data types. **Integration-specific behavior** 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/supplemental-data/overview) 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 eventType: 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 eventType: 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.6464237Z' created: '2022-10-27T09:53:29Z' 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 eventType: 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.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. connection.failed: post: description: Called when a connection failed linking to the SMB. requestBody: content: application/json: schema: $ref: '#/components/schemas/ConnectionWebhook' examples: Connection failed: value: id: ba29118f-5406-4e59-b05c-ba307ca38d01 eventType: connection.failed 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 created: '2022-10-27T09:53:29Z' sourceType: Banking dataConnectionErrors: - statusCode: '403' statusText: User cancelled linking errorMessage: User cancelled erroredOnUtc: '2022-10-27T09:53:29Z' status: Active 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 eventType: 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.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking De-authorized: value: id: ba29118f-5406-4e59-b05c-ba307ca38d01 eventType: 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.6464237Z' created: '2022-10-27T09:53:29Z' 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:29Z' 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 eventType: 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.6464237Z' created: '2022-10-27T09:53:29Z' 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 eventType: 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.6464237Z' created: '2022-10-27T09:53:29Z' 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 with validation warnings: 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 issues: - type: warning.validation message: Something doesn't look right about these invoices. You can see more information in the logs. links: logs: 'https://api.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/sync/743ec94a-8aa4-44bb-8bd4-e1855ee0e74b/validation' portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/pull-history' readMore: 'https://docs.codat.io/using-the-api/get-data-troubleshooting#warning.validation' Read completed without issues: 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 issues: [] 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 with validation warnings: 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 issues: - type: warning.validation message: Something doesn't look right about these invoices. You can see more information in the logs. links: logs: 'https://api.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/sync/743ec94a-8aa4-44bb-8bd4-e1855ee0e74b/validation' portal: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/pull-history' readMore: 'https://docs.codat.io/using-the-api/get-data-troubleshooting#warning.validation' Initial without issues: 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 issues: [] 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:23Z' 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:00Z' completedOnDate: '2023-05-03T10:00:23Z' status: Success record: id: bil_1Nispe2eZvKYlo2Cd31jOCgZ Attachment: value: id: bae71d36-ff47-420a-b4a6-f8c9ddf41140 eventType: '{dataType}.write.successful' generatedDate: '2023-05-03T10:00:23Z' 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:00Z' completedOnDate: '2023-05-03T10:00:23Z' 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:23Z' 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:00Z' completedOnDate: '2023-05-03T10:00:23Z' status: Failed Record timed out: value: id: bae71d36-ff47-420a-b4a6-f8c9ddf41140 eventType: '{dataType}.write.unsuccessful' generatedDate: '2023-05-03T10:00:23Z' 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:00Z' completedOnDate: '2023-05-03T10:00:23Z' status: TimedOut Attachment: value: id: bae71d36-ff47-420a-b4a6-f8c9ddf41140 eventType: '{dataType}.write.unsuccessful' generatedDate: '2023-05-03T10:00:23Z' 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:00Z' completedOnDate: '2023-05-03T10:00:23Z' 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. 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. 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: title: Tags type: object maxProperties: 10 propertyNames: pattern: '^.{1,27}$' additionalProperties: type: string maxLength: 100 description: A collection of user-defined key-value pairs that store custom metadata against the company. referenceParentCompany: $ref: '#/components/schemas/Company/definitions/companyReference' nullable: true description: The parent entity or controlling organization of this company. Null if the company has no parent. referenceSubsidiaryCompanies: type: array nullable: false description: A list of subsidiary companies owned or controlled by this entity. Empty if the company has no children. minItems: 0 items: $ref: '#/components/schemas/Company/definitions/companyReference' 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 products: - spend-insights - lending CompanyAccessToken: title: Company access token description: Details of the access token provisioned for a company. type: object allOf: - $ref: '#/components/schemas/CompanyAccessToken/definitions/accessToken' definitions: accessToken: title: Access token type: object properties: expiresIn: type: integer description: The number of seconds until the access token expires. example: 86400 accessToken: type: string description: The access token for the company. tokenType: type: string description: The type of token. example: Bearer required: - expiresIn - accessToken - tokenType examples: - expiresIn: 86400 accessToken: string tokenType: Bearer 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 CompanyUpdateRequest: title: Update 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: $ref: '#/components/schemas/CompanyRequestBody/properties/description' tags: $ref: '#/components/schemas/Company/definitions/companyDetails/properties/tags' 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: true 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' 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 - connection.failed 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 accounting software, commerce software, or open banking provider 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. DataStatus: title: Data status description: Describes the state of data in the Codat cache for a company and data type type: object required: - dataType - 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 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:00Z' - '2022-10-23' 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' 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. 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' 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: Read result 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: $ref: '#/components/schemas/ReadCompletedWebhook/definitions/dataTypeReadSummary' dataTypeReadSummary: title: Summary of data type reads 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' issues: type: array nullable: true description: A array of issues encountered during a data read. items: $ref: '#/components/schemas/ReadCompletedWebhook/definitions/issue' customProductReadCompleteWebhook: title: Read completed webhook type: object properties: id: $ref: '#/components/schemas/ReadCompletedWebhook/properties/id' eventType: $ref: '#/components/schemas/ReadCompletedWebhook/properties/eventType' generatedDate: $ref: '#/components/schemas/ReadCompletedWebhook/properties/generatedDate' payload: $ref: '#/components/schemas/ReadCompletedWebhook/definitions/customProductReadCompleteWebhookPayload' customProductReadCompleteWebhookPayload: title: Read result webhook payload type: object properties: referenceCompany: $ref: '#/components/schemas/Company/definitions/companyReference' modifiedFromDate: $ref: '#/components/schemas/ReadCompletedWebhook/definitions/readCompletedWebhookPayload/properties/modifiedFromDate' dataTypes: type: array description: Contains all data types configured for the product or a subset of data types defined in the manual refresh call. items: type: object title: Summary of data type reads properties: connectionId: $ref: '#/components/parameters/connectionId/schema' dataType: $ref: '#/components/schemas/DataStatus/properties/dataType' recordsModified: $ref: '#/components/schemas/ReadCompletedWebhook/definitions/dataTypeReadSummary/properties/recordsModified' status: $ref: '#/components/schemas/PullOperation/properties/status' issues: type: array nullable: true description: A array of issues encountered during a data read. items: $ref: '#/components/schemas/ReadCompletedWebhook/definitions/issue' issue: title: Issue type: object description: Details of a problem encountered during a data read. properties: type: type: string description: The type of issue. example: warning.validation message: type: string description: A message describing the issue. example: Something doesn't look right about these accounts from Xero. You can see more information in the logs. links: title: Links type: object properties: logs: type: string description: 'A link to the validation logs, providing details on any errors or warnings encountered.' example: 'https://api.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/sync/{datasetId}/validation' portal: type: string description: A link to the company's past data read history in the Codat portal. example: 'https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/pull-history' readMore: type: string description: A link to Codat's documentation with additional information on how to troubleshoot this issue. example: 'https://docs.codat.io/using-the-api/get-data-troubleshooting#warning.validation' 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 ValidationResult: title: Validation result type: object properties: errors: type: array items: $ref: '#/components/schemas/ValidationResult/definitions/validationItem' warnings: type: array items: $ref: '#/components/schemas/ValidationResult/definitions/validationItem' definitions: validationItem: title: Validation item type: object properties: ruleId: type: string description: The unique identifier of the rule that wasn't met. itemId: type: string description: The unique identifier of the item that was validated. message: type: string description: The message that describes the validation warning or error. validatorName: type: string description: The name of the validator that was used to validate the item. 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 nullable: true 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 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' 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' 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/ApiKeyDetails) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/platform-api#/operations/list-api-keys), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.' type: apiKey in: header x-speakeasy-example: Basic BASE_64_ENCODED(API_KEY)