openapi: 3.1.0 servers: - description: Production url: 'https://api.codat.io' info: title: Bill pay kit description: |- The API reference for the Bill Pay kit. The bill pay kit is an API and a set of supporting tools designed to integrate a bill pay flow into your app as quickly as possible. It's ideal for facilitating essential bill payment processes within your SMB's accounting software. [Explore product](https://docs.codat.io/payables/bill-pay-kit) | [See OpenAPI spec](https://github.com/codatio/oas) --- ## Endpoints | Endpoints | Description | | :- |:- | | Companies | Create and manage your SMB users' companies. | | Connections | Create new and manage existing data connections for a company. | | Company information | View company profile from the source platform. | | Bills | Get, create, and update Bills. | | Bill payments | Get, create, and update Bill payments. | | Suppliers | Get, create, and update Suppliers. | | Bank accounts | Create a bank account for a given company's connection. | version: 3.0.0 contact: name: Codat email: support@codat.io termsOfService: 'https://www.codat.io/legals/' security: - auth_header: [] x-speakeasy-retries: strategy: backoff backoff: initialInterval: 500 maxInterval: 60000 maxElapsedTime: 3600000 exponent: 1.5 statusCodes: - 408 - 429 - 5XX retryConnectionErrors: true x-speakeasy-name-override: - operationId: ^list-.*? methodNameOverride: list - operationId: ^list-.*?-attachments methodNameOverride: list-attachments - operationId: ^get-.*? methodNameOverride: get - operationId: ^get-create-.*?-model methodNameOverride: get-create-model - operationId: ^get-create-update.*?-model methodNameOverride: get-create-update-model - operationId: ^get-.*?-attachment methodNameOverride: get-attachment - operationId: ^update-.*? methodNameOverride: update - operationId: ^create-.*? methodNameOverride: create - operationId: ^delete-.*? methodNameOverride: delete - operationId: ^delete-.*?-attachment methodNameOverride: delete-attachment - operationId: ^download-.*?-attachment methodNameOverride: download-attachment - operationId: ^upload-.*?-attachment methodNameOverride: upload-attachment x-codat-docs-path: sync-for-payables-api x-codat-keep-docs-paths-local: true x-codat-speakeasy-pagination: type: offsetLimit inputs: - name: page in: parameters type: page outputs: results: $.results tags: - name: Companies description: Create and manage your SMB users' companies. - name: Connections description: Create new and manage existing data connections for a company. - name: Company information description: View company profile from the source platform. - name: Bills description: 'Get, create, and update Bills.' - name: Bill payments description: 'Get, create, and update Bill payments.' - name: Suppliers description: 'Get, create, and update Suppliers.' - name: Bank accounts description: Create a bank account for a given company's connection. paths: /companies: get: summary: List companies tags: - Companies responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Companies' examples: One company: value: results: - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 name: My Test Company description: My Test Company make testing software platform: '' redirect: 'https://link.codat.io/company/3fa85f64-5717-4562-b3fc-2c963f66afa6' lastSync: '2022-01-01T12:30:00.000Z' dataConnections: - id: 51baa045-4836-4317-a42e-3542e991e581 integrationId: 1c312d69-e638-46d4-ad31-72e6c3ba8390 integrationKey: vjms sourceId: 396c3158-5dd7-481b-a7c4-a795ca31792b platformName: Pandle linkUrl: 'https://link-api.codat.io/companies/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections/51baa045-4836-4317-a42e-3542e991e581/start' status: Linked lastSync: '2022-01-01T12:30:00.000Z' created: '2022-01-01T11:30:00Z' sourceType: Accounting created: '2022-01-01T11:30:00Z' createdByUserName: Mike Smith pageNumber: 1 pageSize: 100 totalResults: 1 _links: current: href: /companies?page=1&pageSize=100 self: href: /companies List of Companies: value: results: - id: d1568dde-adf6-11ed-afa1-0242ac120002 name: Technicalium description: 'Technology services, including web and app design and development' platform: '' redirect: 'https://link.codat.io/company/d1568dde-adf6-11ed-afa1-0242ac120002' lastSync: '2022-01-01T12:30:00.000Z' dataConnections: - id: 51baa045-4836-4317-a42e-3542e991e581 integrationId: 1c312d69-e638-46d4-ad31-72e6c3ba8390 integrationKey: vjms sourceId: 396c3158-5dd7-481b-a7c4-a795ca31792b platformName: Pandle linkUrl: 'https://link-api.codat.io/companies/d1568dde-adf6-11ed-afa1-0242ac120002/connections/51baa045-4836-4317-a42e-3542e991e581/start' status: Linked lastSync: '2022-01-01T12:30:00.000Z' created: '2022-01-01T11:30:00Z' sourceType: Accounting created: '2022-01-01T11:30:00Z' createdByUserName: Joe Bloggs - id: 096db70b-78de-4ff0-aa98-299cb5fe17a0 name: Godata description: A new digital agency with a passion for creating amazing digital experiences platform: '' redirect: 'https://link.codat.io/company/096db70b-78de-4ff0-aa98-299cb5fe17a0' lastSync: '2022-01-01T12:30:00.000Z' dataConnections: - id: a70bc148-dc21-46b2-a257-d9c58ac15cbb integrationId: 1c312d69-e638-46d4-ad31-72e6c3ba8390 integrationKey: vjms sourceId: 396c3158-5dd7-481b-a7c4-a795ca31792b platformName: Pandle linkUrl: 'https://link-api.codat.io/companies/096db70b-78de-4ff0-aa98-299cb5fe17a0/connections/a70bc148-dc21-46b2-a257-d9c58ac15cbb/start' status: Linked lastSync: '2022-01-01T12:30:00.000Z' created: '2022-01-01T11:30:00Z' sourceType: Accounting created: '2022-01-01T11:30:00Z' createdByUserName: Mike Smith pageNumber: 1 pageSize: 100 totalResults: 2 _links: current: href: /companies?page=1&pageSize=100 self: href: /companies '400': $ref: '#/components/responses/Malformed-Query' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' operationId: list-companies description: "\uFEFFThe *List companies* endpoint returns a list of [companies] associated to your instances.\n\nA [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data." parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/orderBy' post: summary: Create company tags: - Companies operationId: create-company responses: '200': description: OK content: application/json: x-speakeasy-usage-example: true schema: $ref: '#/components/schemas/Company' examples: With no description: value: id: ab12c58d-a678-4ebf-a159-ae99e1807bd0 name: Technicalium description: '' platform: '' redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0' dataConnections: [] created: '2022-11-10T10:45:18.1950523Z' createdByUserName: Dan Tzabar With a description: value: id: ab12c58d-a678-4ebf-a159-ae99e1807bd0 name: Technicalium description: 'Technology services, including web and app design and development' platform: '' redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0' dataConnections: [] created: '2022-11-10T10:45:18.1950523Z' createdByUserName: Dan Tzabar With a tag: value: id: ab12c58d-a678-4ebf-a159-ae99e1807bd0 name: Technicalium description: '' platform: '' redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0' dataConnections: [] created: '2022-11-10T10:45:18.1950523Z' createdByUserName: Dan Tzabar tags: region: us '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' description: "\uFEFFUse the *Create company* endpoint to create a new [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) that represents your customer in Codat. \n\nA [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n\nIf forbidden characters (see `name` pattern) are present in the request, a company will be created with the forbidden characters removed. For example, `Company (Codat[1])` with be created as `Company Codat1`." requestBody: content: application/json: schema: $ref: '#/components/schemas/CompanyRequestBody' examples: With no description: value: name: Technicalium With a description: value: name: Technicalium description: 'Technology services, including web and app design and development' '/companies/{companyId}': put: summary: Update company description: "\uFEFFUse the *Update company* endpoint to update both the name and description of the company. \n\nA [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data." operationId: update-company parameters: - $ref: '#/components/parameters/companyId' tags: - Companies responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Company' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' requestBody: content: application/json: schema: $ref: '#/components/schemas/CompanyRequestBody' examples: Update name: value: name: New Name Update description: value: name: Same name description: Additional documents required delete: summary: Delete a company operationId: delete-company parameters: - $ref: '#/components/parameters/companyId' description: "\uFEFFThe *Delete company* endpoint permanently deletes a [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company), its [connections](https://docs.codat.io/sync-for-payables-api#/schemas/Connection) and any cached data. This operation is irreversible.\n\nA [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n" tags: - Companies responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' get: summary: Get company operationId: get-company description: "\uFEFFThe *Get company* endpoint returns a single company for a given `companyId`.\n\nA [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n" parameters: - $ref: '#/components/parameters/companyId' tags: - Companies responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Company' examples: Simple company: value: id: ab12c58d-a678-4ebf-a159-ae99e1807bd0 name: My First Company description: '' platform: '' redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0' dataConnections: [] created: '2022-11-10T10:45:18Z' createdByUserName: Dan Tzabar '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections': get: summary: List connections description: "\uFEFFList the connections for a company." operationId: list-connections tags: - Connections parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/orderBy' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Connections' examples: Connections: value: results: - id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c integrationKey: dfxm sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee platformName: Basiq linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start' status: Linked lastSync: '2022-10-27T10:22:43.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking pageNumber: 0 pageSize: 0 totalResults: 0 _links: self: href: string current: href: string next: href: string previous: href: string '400': $ref: '#/components/responses/Malformed-Query' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' post: summary: Create connection description: "\uFEFFCreates a connection for the company by providing a valid `platformKey`. \n\nUse the [List Integrations](https://docs.codat.io/sync-for-payables-api#/operations/list-integrations) endpoint to access valid platform keys. " parameters: - $ref: '#/components/parameters/companyId' tags: - Connections operationId: create-connection requestBody: content: application/json: schema: type: object properties: platformKey: type: string minLength: 4 maxLength: 4 pattern: '[a-z]{4}' example: gbol description: 'A unique 4-letter key to represent a platform in each integration. View [accounting](https://docs.codat.io/integrations/accounting/overview#platform-keys), [banking](https://docs.codat.io/integrations/banking/overview#platform-keys), and [commerce](https://docs.codat.io/integrations/commerce/overview#platform-keys) platform keys.' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Connection' examples: Connection: value: id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c integrationKey: dfxm sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee platformName: Basiq linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start' status: Linked lastSync: '2022-10-27T10:22:43.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections/{connectionId}': get: summary: Get connection operationId: get-connection description: "\uFEFFReturns a specific connection for a company when valid identifiers are provided. If the identifiers are for a deleted company and/or connection, a not found response is returned." tags: - Connections parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Connection' examples: Connection: value: id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c integrationKey: dfxm sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee platformName: Basiq linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start' status: Linked lastSync: '2022-10-27T10:22:43.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' delete: summary: Delete connection operationId: delete-connection description: "\uFEFFRevoke and remove a connection from a company.\nThis operation is not reversible. The end user would need to reauthorize a new data connection if you wish to view new data for this company." parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' tags: - Connections responses: '200': description: OK '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' patch: summary: Unlink connection description: "\uFEFFThis allows you to deauthorize a connection, without deleting it from Codat. This means you can still view any data that has previously been pulled into Codat, and also lets you re-authorize in future if your customer wishes to resume sharing their data." operationId: unlink-connection x-speakeasy-name-override: unlink tags: - Connections parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Connection' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' requestBody: content: application/json: schema: title: Update connection x-internal: true type: object properties: status: $ref: '#/components/schemas/Connection/definitions/dataConnectionStatus' description: The current authorization status of the data connection. nullable: true additionalProperties: false examples: Example: value: status: Unlinked description: '' '/companies/{companyId}/connections/{connectionId}/payables/info': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' get: summary: Get company information description: |+ Use the *Get company information* endpoint to return information about the company available from the underlying accounting software. operationId: get-company-information tags: - Company information responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanyInformation' examples: Company information: value: companyName: Bank of Dave baseCurrency: GBP '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections/{connectionId}/payables/mappingOptions/bills': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' get: summary: Get bill mapping options description: "\uFEFFUse the *Get mapping options - Bills* endpoint to return a list of available mapping options for a given company's connection ID.\n\nBy default, this endpoint returns a list of active accounts and tax rates. You can use [querying](https://docs.codat.io/using-the-api/querying) to change that.\n\nMapping options are a set of accounts and tax rates used to configure the SMB's payables integration." operationId: get-mapping-options-bills x-speakeasy-name-override: get-bill-options tags: - Bills parameters: - $ref: '#/components/parameters/continuationToken' - $ref: '#/components/parameters/statusQuery' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BillMappingOptions' examples: Mapping options: value: accounts: - id: 1b6266d1-1e44-46c5-8eb5-a8f98e03124e nominalCode: 879-i name: Accounts payable type: Liability currency: GBP status: Active sourceModifiedDate: 2022-10-23T00:00:00.000Z taxRates: - id: d2939064-dd3a-4c0f-9865-a238c2193515 name: VAT @ 20% code: VAT20 effectiveTaxRate: 20 totalTaxRate: 20 status: Active sourceModifiedDate: 2022-10-23T00:00:00.000Z pagination: continuationToken: eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ== '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections/{connectionId}/payables/mappingOptions/payments': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' get: summary: Get payment mapping options description: "Use the *Get mapping options - Payments* endpoint to return a list of available mapping options for a given company's connection ID.\r\n\r\nBy default, this endpoint returns a list of active bank accounts. You can use [querying](https://docs.codat.io/using-the-api/querying) to change that.\r\n\r\nMapping options are a set of bank accounts used to configure the SMB's payables integration." operationId: get-mapping-options-payments x-speakeasy-name-override: get-payment-options tags: - Bill payments parameters: - $ref: '#/components/parameters/continuationToken' - $ref: '#/components/parameters/statusQuery' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PaymentMappingOptions' examples: Mapping options: value: bankAccounts: - id: 3d5a8e00-d108-4045-8823-7f342676cffa name: Bank of Dave current account accountNumber: '12345678' currency: GBP nominalCode: '1234567' sortCode: '123456' status: Active accountType: Debit sourceModifiedDate: 2022-10-23T00:00:00.000Z pagination: continuationToken: eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ== '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections/{connectionId}/payables/bills': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' get: summary: List bills description: |- The *List bills* endpoint returns a list of [bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) for a given company's connection. [Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services. By default, the endpoint will return all bills with a status of 'Open' & 'PartiallyPaid' to show all oustanding bills. operationId: list-bills tags: - Bills parameters: - $ref: '#/components/parameters/continuationToken' - name: query in: query required: false schema: type: string examples: Status (open): value: status=Open Status (partially paid): value: status=PartiallyPaid Source modified date: value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z' Status (open) & source modified date: value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Open' Status (partially paid) & source modified date: value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=PartiallyPaid' description: 'Codat query string allows you to filter by `status` and `sourceModifiedDate`. Learn more about Codat''s query string [here](https://docs.codat.io/using-the-api/querying). Platfrom specfic statuses: Xero supports Open | PartiallyPaid | Paid | Void | Draft. Qbo supports Open | PartiallyPaid | Paid. FreeAgent supports Open | PartiallyPaid | Paid.' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Bill/definitions/bills' examples: Bills: value: results: - id: '18' reference: '12' supplierRef: id: '4' supplierName: BILLy elliot issueDate: '2019-05-13T00:00:00' dueDate: '2019-05-13T00:00:00' currency: GBP currencyRate: '1,' lineItems: - description: Dance shoes unitAmount: 5 quantity: 1 taxAmount: 0 accountRef: id: '16' taxRateRef: id: NON totalAmount: 5 status: Open totalAmount: 5 amountDue: 0 sourceModifiedDate: '2022-05-26T10:34:10Z' - id: '22' reference: '12' supplierRef: id: '4' supplierName: BILLy elliot issueDate: '2019-05-13T00:00:00' dueDate: '2019-05-13T00:00:00' currency: GBP currencyRate: 1 lineItems: - description: Dance shoes unitAmount: 5 quantity: 1 taxAmount: 0 accountRef: id: '16' taxRateRef: id: NON totalAmount: 5 status: Paid totalAmount: 5 amountDue: 0 sourceModifiedDate: '2022-05-26T10:34:10Z' pagination: continuationToken: eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ== '400': $ref: '#/components/responses/Malformed-Query' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' post: summary: Create bill description: |- The *Create bill* endpoint creates a new [bill](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) for a given company's connection. [Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services. operationId: create-bill tags: - Bills parameters: - in: header name: Idempotency-Key description: A unique identifier to ensure idempotent behaviour for subsequent requests. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Bill/definitions/billPrototype' examples: Create bill: value: reference: bill_b8qmmj4ksf1suax supplierRef: id: 1262c350-fe0f-40ec-aeff-41c95b4a45af supplierName: DIISR - Small Business Services issueDate: '2023-04-23T00:00:00' dueDate: '2023-04-23T00:00:00' currency: GBP currencyRate: 1 lineItems: - description: Half day training - Microsoft Office unitAmount: 1800 quantity: 1 taxAmount: 360 totalAmount: 2160 accountRef: id: 46f9461e-788b-4906-8b74-d1ea17f6dc10 taxRateRef: id: INPUT2 - description: Desktop/network support via email & phone.Per month fixed fee for minimum 20 hours/month. unitAmount: 4000 quantity: 1 taxAmount: 800 totalAmount: 4800 accountRef: id: f96c9458-d724-47bf-8f74-a9d5726465ce taxRateRef: id: INPUT2 - description: Stationery charges unitAmount: 32 quantity: 8 taxAmount: 51.2 totalAmount: 307.2 accountRef: id: cba6527d-f102-4538-b421-e483233e9d5a taxRateRef: id: INPUT2 status: Open responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Bill' examples: Created bill: value: id: bill-1029932 reference: bill_b8qmmj4ksf1suax supplierRef: id: 1262c350-fe0f-40ec-aeff-41c95b4a45af supplierName: DIISR - Small Business Services issueDate: '2023-04-23T00:00:00' dueDate: '2023-04-23T00:00:00' currency: GBP lineItems: - description: Half day training - Microsoft Office unitAmount: 1800 quantity: 1 taxAmount: 360 totalAmount: 2160 accountRef: id: 46f9461e-788b-4906-8b74-d1ea17f6dc10 taxRateRef: id: INPUT2 - description: Desktop/network support via email & phone.Per month fixed fee for minimum 20 hours/month. unitAmount: 4000 quantity: 1 taxAmount: 800 totalAmount: 4800 accountRef: id: f96c9458-d724-47bf-8f74-a9d5726465ce taxRateRef: id: INPUT2 - description: Stationery charges unitAmount: 32 quantity: 8 taxAmount: 51.2 totalAmount: 307.2 accountRef: id: cba6527d-f102-4538-b421-e483233e9d5a taxRateRef: id: INPUT2 status: Open totalAmount: 7267.2 amountDue: 7267.2 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '409': $ref: '#/components/responses/Idempotency-Conflict' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections/{connectionId}/payables/bills/{billId}/attachments': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' - $ref: '#/components/parameters/billId' post: summary: Upload bill attachment description: "The *Upload bill attachment* endpoint uploads an attachment and assigns it against a specific `billId`.\r\n\r\n[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services." operationId: upload-bill-attachment tags: - Bills requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/AttachmentUpload' responses: '201': description: Created '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections/{connectionId}/bills/{billId}/attachments': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' - $ref: '#/components/parameters/billId' get: tags: - Bills responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Attachment' examples: Info: value: id: 422f093f-e556-4bf3-91c0-93af70c3e850 name: receipt.png contentType: image/png dateCreated: '2022-10-23T00:00:00.000Z' fileSize: 100 includeWhenSent: true sourceModifiedDate: '2022-05-26T10:34:10Z' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' operationId: list-bill-attachments summary: List bill attachments description: "The *List bill attachments* endpoint returns a list of attachments available to download for a given `billId`.\r\n\r\n[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services." '/companies/{companyId}/connections/{connectionId}/payables/bills/{billId}/attachments/{attachmentId}/download': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' - $ref: '#/components/parameters/billId' - $ref: '#/components/parameters/attachmentId' get: summary: Download bill attachment description: | The *Download bill attachment* endpoint downloads a specific attachment for a given `billId` and `attachmentId`. [Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services. Check out our [coverage explorer](https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=bills) for integrations that support downloading a bill attachment. operationId: download-bill-attachment tags: - Bills responses: '200': description: Success content: application/octet-stream: schema: title: Data type: string format: binary '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections/{connectionId}/payables/bills/{billId}/payment': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' - $ref: '#/components/parameters/billId' - in: header name: Idempotency-Key description: A unique identifier to ensure idempotent behaviour for subsequent requests. schema: type: string post: summary: Create bill payment description: |- The *Create bill payment* endpoint creates a new [bill payment](https://docs.codat.io/sync-for-payables-api#/schemas/BillPayment) for a given company's connection. [Bill payments](https://docs.codat.io/sync-for-payables-api#/schemas/BillPayment) are an allocation of money within any Accounts Payable account. operationId: create-bill-payment tags: - Bill payments requestBody: content: application/json: schema: $ref: '#/components/schemas/BillPayment/definitions/billPaymentPrototype' examples: Bill payment example: value: amount: 22 currencyRate: 1 date: '2022-10-23T00:00:00.000Z' accountRef: id: 7bda9f44sr56 reference: Bill Payment against bill c13e37b6 dfaa-4894-b3be-9fe97bda9f44 responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/BillPayment' examples: Bill payment: value: id: billPayment-1029932 amount: 22 currencyRate: 1 date: '2022-10-23T00:00:00.000Z' accountRef: id: 7bda9f44sr56 reference: Bill Payment against bill c13e37b6 dfaa-4894-b3be-9fe97bda9f44 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '409': $ref: '#/components/responses/Idempotency-Conflict' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections/{connectionId}/payables/suppliers': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' get: tags: - Suppliers summary: List suppliers description: |- The *List suppliers* endpoint returns a list of [suppliers](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) for a given company's connection. [Suppliers](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) are people or organizations that provide something, such as a product or service. By default, this endpoint returns a list of active and archived suppliers. You can use [querying](https://docs.codat.io/using-the-api/querying) to change that. For example, to retrieve only active suppliers (i.e. `status=Active`) or suppliers created within the specified number of days (e.g. `sourceModifiedDate>2023-12-15T00:00:00.000Z`), query the endpoint as follows: `/payables/suppliers?query=sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Active`.For example, to retrieve active suppliers modified after a particular date use `query=sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Active`. operationId: list-suppliers parameters: - $ref: '#/components/parameters/continuationToken' - name: query in: query required: false schema: type: string examples: Source modified date: value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z' Status (active): value: status=Active Status (archived): value: status=Archived Status (active) & source modified date: value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Active' Status (archived) & source modified date: value: 'sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Archived' description: 'Codat query string allows you to filter by `sourceModifiedDate` or if a supplier is `Active` or `Archived` in the accounting software. Learn more about Codat''s query string [here](https://docs.codat.io/using-the-api/querying).' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Supplier/definitions/suppliers' examples: Suppliers: value: results: - id: c523e12f-8b74-4d3a-bbd8-32d7a2f598b4 supplierName: City Limousines contactName: Martin Dale emailAddress: martyd@citylim.co phone: 07999 999999 addresses: - type: Billing line1: Unit 51 line2: Bakersfield Industrial Estate city: Bakersfield region: California country: USA postalcode: '93308' status: Active balance: 100 defaultCurrency: GBP sourceModifiedDate: '2022-10-23T00:00:00Z' - id: '41' supplierName: AI Support contactName: AI Support addresses: - type: Billing line1: test region: string country: Djibouti status: Active defaultCurrency: GBP sourceModifiedDate: '2022-12-07T10:48:18Z' pagination: continuationToken: eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ== '400': $ref: '#/components/responses/Malformed-Query' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' post: tags: - Suppliers summary: Create supplier description: "The *Create supplier* endpoint creates a new [supplier](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) for a given company's connection.\r\n\r\n[Suppliers](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) are people or organizations that provide something, such as a product or service.\r\n" operationId: create-supplier parameters: - in: header name: Idempotency-Key description: A unique identifier to ensure idempotent behaviour for subsequent requests. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Supplier/definitions/supplierPrototype' examples: Suppliers: value: supplierName: Greggs contactName: Greg Greggs emailAddress: greg@greggs.com phone: +44 (0)1223 322410 addresses: - type: Billing line1: Flat 1 line2: 2 Dennis Avenue city: London region: Camden country: GBR postalCode: EC1N 7TE status: Active defaultCurrency: GBP responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Supplier' examples: Suppliers: value: id: sup-10933920 supplierName: Greggs contactName: Greg Greggs emailAddress: greg@greggs.com phone: +44 (0)1223 322410 address: - type: Billing line1: Flat 1 line2: 2 Dennis Avenue city: London region: Camden country: GBR postalCode: EC1N 7TE status: Active defaultCurrency: GBP '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/connections/{connectionId}/payables/bankAccounts': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' post: tags: - Bank accounts summary: Create bank account parameters: - in: header name: Idempotency-Key description: A unique identifier to ensure idempotent behaviour for subsequent requests. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BankAccount/definitions/bankAccountPrototype' examples: Bank account example: value: id: fb623ab2-f6ff-4b22-b7d3-b7cc2a4aa0ea nominalCode: '22' name: Plutus - Payables - Bank Account 12 accountNumber: 0120 0440 sortCode: 50-50-50 currency: GBP accountType: Debit status: Active sourceModifiedDate: 2024-02-22T14:46:43.990Z responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/BankAccount' examples: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' description: "The *Create bank account* endpoint creates a new [bank account](https://docs.codat.io/sync-for-payables-api#/schemas/BankAccount) for a given company's connection.\r\n\r\n[Bank accounts](https://docs.codat.io/sync-for-payables-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution." operationId: create-bank-account webhooks: client.rateLimit.reached: post: description: Called when your client’s request count to Codat's API surpasses the allocated quota. requestBody: content: application/json: schema: $ref: '#/components/schemas/ClientRateLimitWebhook' examples: Reached: value: id: 743ec94a-8aa4-44bb-8bd4-e1855ee0e74b eventType: client.rateLimit.reached generatedDate: '2024-09-01T00:00:00Z' payload: dailyQuota: 12000 quotaRemaining: 0 expiryDate: '2024-09-01T12:14:14Z' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. client.rateLimit.reset: post: description: 'Called when your client''s rate limit quota is reset, allowing additional requests to Codat''s API.' requestBody: content: application/json: schema: $ref: '#/components/schemas/ClientRateLimitWebhook' examples: Reset: value: id: 743ec94a-8aa4-44bb-8bd4-e1855ee0e74b eventType: client.rateLimit.reset generatedDate: '2024-09-01T00:00:00Z' payload: dailyQuota: 12000 quotaRemaining: 11993 expiryDate: '2024-09-01T23:59:99Z' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. Client rate limit reached: post: deprecated: true description: |- Called when your client’s requests to Codat's API exceed the allocated quota. **Note: This event type is deprecated. Developers should now use the `client.rateLimit.reached` event for handling rate limit notifications.** requestBody: content: application/json: schema: $ref: '#/components/schemas/ClientRateLimitReachedWebhook' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. Client rate limit reset: post: deprecated: true description: |- Called when the rate limit quota has reset for the client, and more requests to Codat's API are available. Note: This event type is deprecated. Developers should now use the `client.rateLimit.reset` event for handling rate limit notifications. requestBody: content: application/json: schema: $ref: '#/components/schemas/ClientRateLimitResetWebhook' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. components: schemas: Address: title: Address x-internal: true type: object properties: type: $ref: '#/components/schemas/Address/definitions/addressType' line1: type: string nullable: true description: Line 1 of the customer address. line2: type: string nullable: true description: Line 2 of the customer address. city: type: string nullable: true description: City of the customer address. region: type: string nullable: true description: Region of the customer address. country: type: string nullable: true description: 'Country of the customer''s address. For NetSuite, use the 2-digit [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code.' postalCode: type: string nullable: true description: Postal code or zip code. definitions: addressType: description: The type of the address type: string enum: - Unknown - Billing - Delivery Attachment: title: Attachment description: |2- The Codat API supports pulling and pushing of file attachments for invoices, bills, direct costs, and direct incomes. > **Retrieving attachments** > > If a company is authorized, you can query the Codat API to read, download, and upload attachments without requiring a fresh sync of data. Unlike other data types, Codat doesn't support [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings) for attachments. Note that different integrations have different requirements for file size and extension of attachments. | Integration | File size | File extension | |-------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | Xero | 4 MB | 7Z, BMP, CSV, DOC, DOCX, EML, GIF, JPEG, JPG, KEYNOTE, MSG, NUMBERS, ODF, ODS, ODT, PAGES, PDF, PNG, PPT, PPTX, RAR, RTF, TIF, TIFF, TXT, XLS, XLSX, ZIP | | QuickBooks Online | 100 MB | AI, CSV, DOC, DOCX, EPS, GIF, JPEG, JPG, ODS, PAGES, PDF, PNG, RTF, TIF, TXT, XLS, XLSX, XML | | NetSuite | 100 MB | BMP, CSV, XLS, XLSX, JSON, PDF, PJPG, PJPEG, PNG, TXT, SVG, TIF, TIFF, DOC, DOCX, ZIP | | Dynamics 365 Business Central | 350 MB | Dynamics do not explicitly outline which file types are supported but they do state here that "You can attach any type of file, such as text, image, or video files". | type: object allOf: - type: object properties: id: type: string description: 'Identifier for the attachment, unique for the company in the accounting software.' name: type: string nullable: true description: Name of the attachment file. contentType: type: string nullable: true description: |- File type of the attachment. This is represented by appending the file type to the [IETF standard file naming requirements](https://tools.ietf.org/html/rfc6838). For example, for a jpeg file the output is **image/jpeg**. Supported file types vary per platform. dateCreated: $ref: '#/components/schemas/Connection/properties/created' fileSize: type: integer format: int32 nullable: true description: 'File size in bytes. For example, if this reads **46153**, then the file size is 46kb.' includeWhenSent: type: boolean description: 'If `true`, then the attachment is included with the associated invoice, bill or direct costs when it is printed, emailed, or sent to a customer, if the underlying accounting software allows this.' - title: Source Modified Date x-internal: true type: object nullable: true properties: sourceModifiedDate: allOf: - $ref: '#/components/schemas/Connection/properties/created' - description: |- The date when a record was last modified in the source platform, usually by the business or a business process. For example, when payments are made against an invoice. It is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when: - Pulling attachments - The integration platform does not provide modification dates for a data type - A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred - A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records In Codat's data model, dates and times are represented using the ISO 8601 standard. AttachmentUpload: title: Attachment upload type: object x-internal: true required: - file properties: file: $ref: '#/components/schemas/AttachmentUpload/definitions/codatFile' definitions: codatFile: type: string description: The file to be uploaded as an attachment. format: binary BankAccount: title: Bank accounts type: object allOf: - properties: id: type: string description: 'Identifier for the bank account, unique for the company in the accounting software.' nominalCode: type: string nullable: true description: Code used to identify each nominal account for a business. name: type: string nullable: true description: Name of the bank account in the accounting software. accountType: title: Bank Account Type x-internal: true enum: - Unknown - Credit - Debit type: string description: |- The type of transactions and balances on the account. For Credit accounts, positive balances are liabilities, and positive transactions **reduce** liabilities. For Debit accounts, positive balances are assets, and positive transactions **increase** assets. accountNumber: type: string nullable: true description: |- Account number for the bank account. Xero integrations Only a UK account number shows for bank accounts with GBP currency and a combined total of sort code and account number that equals 14 digits, For non-GBP accounts, the full bank account number is populated. sortCode: type: string nullable: true description: |- Sort code for the bank account. This is relevant to UK bank accounts. Xero integrations The sort code is only displayed when the currency = GBP and the sort code and account number sum to 14 digits. For non-GBP accounts, this field is not populated. currency: $ref: '#/components/schemas/Bill/properties/currency' description: Base currency of the bank account. status: $ref: '#/components/schemas/BankAccount/definitions/bankAccountStatus' - $ref: '#/components/schemas/Attachment/allOf/1' definitions: bankAccountStatus: type: string description: The current status of the bank account. enum: - Active - Archived bankAccountPrototype: title: Bank account prototype type: object properties: nominalCode: $ref: '#/components/schemas/BankAccount/allOf/0/properties/nominalCode' name: $ref: '#/components/schemas/BankAccount/allOf/0/properties/name' accountType: $ref: '#/components/schemas/BankAccount/allOf/0/properties/accountType' accountNumber: $ref: '#/components/schemas/BankAccount/allOf/0/properties/accountNumber' sortCode: $ref: '#/components/schemas/BankAccount/allOf/0/properties/sortCode' currency: $ref: '#/components/schemas/BankAccount/allOf/0/properties/currency' required: - name - accountType - accountNumber - currency Bill: title: Bill description: "\uFEFFBills are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services." type: object properties: id: type: string description: 'Identifier for the bill, unique for the company in the accounting software.' reference: type: string nullable: true description: User-friendly reference for the bill. supplierRef: $ref: '#/components/schemas/Supplier/definitions/supplierRef' issueDate: allOf: - description: Date of the bill as recorded in the accounting software. - $ref: '#/components/schemas/Connection/properties/created' dueDate: allOf: - description: Date the supplier is due to be paid. - $ref: '#/components/schemas/Connection/properties/created' currency: title: Currency x-internal: true type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR currencyRate: title: Currency rate type: number format: decimal nullable: true description: |- Rate to convert the total amount of the payment into the base currency for the company at the time of the payment. Currency rates in Codat are implemented as the multiple of foreign currency units to each base currency unit. It is not possible to perform the currency conversion with two or more non-base currencies participating in the transaction. For example, if a company's base currency is USD, and it has a bill issued in EUR, then the bill payment must happen in USD or EUR. Where the currency rate is provided by the underlying accounting software, it will be available from Codat with the same precision (up to a maximum of 9 decimal places). For accounting software which do not provide an explicit currency rate, it is calculated as `baseCurrency / foreignCurrency` and will be returned to 9 decimal places. ## Examples with base currency of GBP | Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (GBP) | | :--------------- | :------------- | :------------ | :------------------------- | | **USD** | $20 | 0.781 | £15.62 | | **EUR** | €20 | 0.885 | £17.70 | | **RUB** | ₽20 | 0.011 | £0.22 | ## Examples with base currency of USD | Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (USD) | | :--------------- | :------------- | :------------ | :------------------------- | | **GBP** | £20 | 1.277 | $25.54 | | **EUR** | €20 | 1.134 | $22.68 | | **RUB** | ₽20 | 0.015 | $0.30 | ### Integration-specific details | Integration | Scenario | System behavior | |-------------------|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | QuickBooks Online | Transaction currency differs from base currency | If currency rate value is left `null`, a rate of 1 will be used by QBO by default. To override this, specify a currencyRate in the request body. | lineItems: type: array nullable: true description: Array of Bill line items. items: $ref: '#/components/schemas/Bill/definitions/billLineItem' status: $ref: '#/components/schemas/Bill/definitions/billStatus' totalAmount: type: number format: decimal description: 'Amount of the bill, including tax.' amountDue: type: number format: decimal nullable: true description: Amount outstanding on the bill. sourceModifiedDate: allOf: - $ref: '#/components/schemas/Connection/properties/created' - description: |- The date when a record was last modified in the source platform, usually by the business or a business process. For example, when payments are made against an invoice. It is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when: - Pulling attachments - The integration platform does not provide modification dates for a data type - A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred - A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records In Codat's data model, dates and times are represented using the ISO 8601 standard. required: - supplierRef - issueDate - dueDate - currency - status definitions: billPrototype: title: Bill prototype type: object properties: reference: $ref: '#/components/schemas/Bill/properties/reference' supplierRef: $ref: '#/components/schemas/Supplier/definitions/supplierRef' issueDate: $ref: '#/components/schemas/Bill/properties/issueDate' dueDate: $ref: '#/components/schemas/Bill/properties/dueDate' currency: $ref: '#/components/schemas/Bill/properties/currency' currencyRate: $ref: '#/components/schemas/Bill/properties/currencyRate' lineItems: $ref: '#/components/schemas/Bill/properties/lineItems' status: $ref: '#/components/schemas/Bill/definitions/billStatus' required: - supplierRef - issueDate - dueDate - currency - status billStatus: description: Current state of the bill. If creating a bill the status must be `Open`. type: string enum: - Unknown - Open - PartiallyPaid - Paid - Void - Draft example: Open billLineItem: title: Bill line item type: object properties: description: type: string nullable: true description: Friendly name of the goods or services received. unitAmount: type: number format: decimal description: Unit price of the goods or service. quantity: type: number format: decimal description: Number of units of goods or services received. taxAmount: type: number format: decimal description: Amount of tax applied to the line item. accountRef: $ref: '#/components/schemas/Bill/definitions/billAccountRef' totalAmount: type: number format: decimal nullable: true description: 'Total amount of the line, including tax.' taxRateRef: $ref: '#/components/schemas/Bill/definitions/billTaxRateRef' required: - quantity - unitAmount - taxRateRef - accountRef billAccountRef: title: Account reference type: object description: Reference to the account to which the line item is linked. properties: id: type: string description: '''id'' from the Accounts data type.' billTaxRateRef: title: Tax rate reference type: object description: Reference to the tax rate to which the line item is linked. properties: id: type: string description: Unique identifier for the tax rate in the accounting software. bills: title: Bills type: object properties: results: type: array items: $ref: '#/components/schemas/Bill' pagination: $ref: '#/components/schemas/Pagination' BillEventWebhook: x-internal: true title: Bill event webhook type: object properties: id: type: string format: uuid description: Unique identifier of the bill event. type: type: string description: Type of webhook event. example: payables.bill.created createdDate: type: string description: The datetime in UTC of when the webhook event was produced by Codat. examples: - 2022-10-23T11:03:35.000Z payload: $ref: '#/components/schemas/BillEventWebhook/definitions/billEventPayload' definitions: billEventPayload: title: Bill event payload type: object properties: companyId: $ref: '#/components/parameters/companyId/schema' connectionId: $ref: '#/components/parameters/connectionId/schema' pushOperationKey: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for the push operation. bill: $ref: '#/components/schemas/Bill' BillMappingOptions: x-internal: true title: Mapping options bills description: The bill mapping options for a company's accounting software. type: object properties: accounts: type: array items: $ref: '#/components/schemas/BillMappingOptions/definitions/accountMappingOption' taxRate: type: array items: $ref: '#/components/schemas/BillMappingOptions/definitions/taxRateMappingOption' pagination: $ref: '#/components/schemas/Pagination' definitions: accountMappingOption: title: Account mapping option type: object allOf: - properties: id: type: string description: 'Identifier for the account, unique for the company.' example: 1b6266d1-1e44-46c5-8eb5-a8f98e03124e nominalCode: type: string nullable: true description: Reference given to each nominal account for a business. It ensures money is allocated to the correct account. This code isn't a unique identifier in the Codat system. example: '610' name: type: string nullable: true description: Name of the account. example: Accounts Payable type: type: string nullable: true description: Type of account. example: Liability currency: $ref: '#/components/schemas/Bill/properties/currency' status: $ref: '#/components/schemas/BillMappingOptions/definitions/accountStatus' - $ref: '#/components/schemas/Attachment/allOf/1' taxRateMappingOption: title: Tax rate mapping option type: object allOf: - properties: id: type: string description: 'Identifier for the tax rate, unique for the company in the accounting software.' example: d2939064-dd3a-4c0f-9865-a238c2193515 name: type: string nullable: true description: Codat-augmented name of the tax rate in the accounting software. code: type: string nullable: true description: Code for the tax rate from the accounting software. effectiveTaxRate: type: number format: decimal nullable: true description: See Effective tax rates description. totalTaxRate: type: number format: decimal nullable: true description: Total (not compounded) sum of the components of a tax rate. status: title: Tax rate status type: string enum: - Active - Archived description: |- Status of the tax rate in the accounting software. - `Active` - An active tax rate in use by a company. - `Archived` - A tax rate that has been archived or is inactive in the accounting software. accountStatus: type: string description: The current status of the account. enum: - Active - Archived example: Active BillPayment: title: Bill payment type: object description: '' properties: id: type: string description: 'Identifier for the bill payment, unique for the company in the accounting software.' amount: type: number format: decimal description: Amount of the payment in the bill currency. example: 1329.54 date: allOf: - $ref: '#/components/schemas/Connection/properties/created' - description: Date the bill payment was recorded in the accounting software. reference: type: string nullable: true description: Additional information associated with the payment. example: Bill Payment against bill c13e37b6-dfaa-4894-b3be-9fe97bda9f44 accountRef: $ref: '#/components/schemas/BillPayment/definitions/billPaymentAccountRef' currencyRate: $ref: '#/components/schemas/Bill/properties/currencyRate' definitions: billPaymentPrototype: title: Bill payment prototype type: object properties: amount: $ref: '#/components/schemas/BillPayment/properties/amount' date: $ref: '#/components/schemas/BillPayment/properties/date' reference: $ref: '#/components/schemas/BillPayment/properties/reference' accountRef: $ref: '#/components/schemas/BillPayment/definitions/billPaymentAccountRef' currencyRate: $ref: '#/components/schemas/Bill/properties/currencyRate' required: - amount - date - accountRef billPaymentAccountRef: description: Reference to the bank account / credit card which you are using to pay the bill. type: object properties: id: type: string description: Unique ID of the bank account / credit card required: - id example: amount: 22 date: '2022-10-23T00:00:00.000Z' reference: Bill Payment against bill c13e37b6 dfaa-4894-b3be-9fe97bda9f44 accountRef: id: 9e32cbf8-e7d5-4d4d-a593-08d550682aab currencyRate: 1 ClientRateLimitReachedWebhook: title: Client rate limit reached webhook x-internal: true description: Webhook request body for a client that has reached their rate limit. type: object properties: ClientId: $ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/ClientId' ClientName: $ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/ClientName' RuleId: $ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/RuleId' RuleType: $ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/RuleType' AlertId: $ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/AlertId' Message: $ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/Message' Data: $ref: '#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData' definitions: ClientRateLimitReachedWebhookData: type: object title: Client rate limit reached webhook data properties: DailyQuota: type: integer description: The number of available requests per day. ExpiresUtc: $ref: '#/components/schemas/Connection/properties/created' description: The date time in UTC when your daily quota is reset. examples: - ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140 ClientName: Bank of Dave RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac RuleType: Rate Limit Reached AlertId: a9367074-b5c3-42c4-9be4-be129f43577e Message: The current daily rate limit quota of 1000 requests for bae71d36-ff47-420a-b4a6-f8c9ddf41140 has been reached. Data: DailyQuota: 1000 ExpiresUtc: '2023-05-03T00:00:00Z' ClientRateLimitResetWebhook: title: Client rate limit reset webhook x-internal: true description: Webhook request body for a client that has had their rate limit reset. type: object properties: ClientId: title: Client ID type: string format: uuid description: Unique identifier for your client in Codat. ClientName: type: string description: Name of your client in Codat. RuleId: type: string format: uuid description: Unique identifier for the rule. deprecated: true RuleType: type: string x-stoplight: id: 34d52a089f08a description: The type of rule. AlertId: type: string format: uuid description: Unique identifier of the webhook event. Message: type: string description: A human-readable message about the webhook. Data: $ref: '#/components/schemas/ClientRateLimitResetWebhook/definitions/ClientRateLimitResetWebhookData' definitions: ClientRateLimitResetWebhookData: type: object title: Client rate limit reset webhook data properties: QuotaRemaining: type: integer description: Total number of requests remaining for your client. nullable: true ResetReason: type: string description: The reason for your rate limit quota being reset. DailyQuota: $ref: '#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/DailyQuota' nullable: true ExpiresUtc: $ref: '#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/ExpiresUtc' nullable: true examples: - ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140 ClientName: Bank of Dave RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac RuleType: Rate Limit Reset AlertId: a9367074-b5c3-42c4-9be4-be129f43577e Message: The current daily rate limit quota for client 30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e has been reset to 1000 requests. Data: QuotaRemaining: 1000 ResetReason: The quota was reset because it is a new day. DailyQuota: 1000 ExpiresUtc: '2023-05-03T00:00:00Z' ClientRateLimitWebhook: title: Client rate limit webhook type: object properties: id: type: string format: uuid example: 743ec94a-8aa4-44bb-8bd4-e1855ee0e74b description: Unique identifier of the event. eventType: type: string description: The type of event. examples: - client.rateLimit.reset - client.rateLimit.reached generatedDate: $ref: '#/components/schemas/Connection/properties/created' description: The date time in UTC the event was generated in Codat. payload: $ref: '#/components/schemas/ClientRateLimitWebhook/definitions/clientRateLimitWebhookPayload' definitions: clientRateLimitWebhookPayload: title: Client rate limit webhook payload type: object properties: dailyQuota: type: integer description: The number of available requests per day. quotaRemaining: type: integer description: Total number of requests remaining for your client. expiryDate: $ref: '#/components/schemas/Connection/properties/created' description: The date time in UTC when your daily quota is reset. Companies: title: Companies x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/Company' - $ref: '#/components/schemas/PagingInfo' Company: title: Company description: "\uFEFFIn Codat, a company represents a business sharing access to their data. Each company can have multiple [connections](https://docs.codat.io/sync-for-payables-api#/schemas/Connection) to different data sources such as one connection to [Xero](https://docs.codat.io/integrations/accounting/xero/accounting-xero) for accounting data, two connections to [Plaid](https://docs.codat.io/integrations/banking/plaid/banking-plaid) for two bank accounts and a connection to [Zettle](https://docs.codat.io/integrations/commerce/zettle/commerce-zettle) for POS data.\n\nTypically each company is one of your customers.\n\nWhen you create a company, you can specify a `name` and we will automatically generate a unique `id` for the company. You can also add a `description` to store any additional information about the company." type: object allOf: - $ref: '#/components/schemas/Company/definitions/companyDetails' - type: object properties: dataConnections: type: array items: $ref: '#/components/schemas/Connection' definitions: companyDetails: title: Company details type: object properties: id: $ref: '#/components/parameters/companyId/schema' name: type: string description: The name of the company example: Codat Ltd. description: $ref: '#/components/schemas/CompanyRequestBody/properties/description' nullable: true redirect: type: string format: uri description: 'The `redirect` [Link URL](https://docs.codat.io/auth-flow/authorize-hosted-link) enabling the customer to start their auth flow journey for the company.' example: 'https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739' lastSync: $ref: '#/components/schemas/Connection/properties/created' nullable: true created: $ref: '#/components/schemas/Connection/properties/created' createdByUserName: type: string description: Name of user that created the company in Codat. nullable: true products: type: array items: type: string description: An array of products that are currently enabled for the company. tags: type: object maxProperties: 10 propertyNames: pattern: '^.{1,27}$' additional properties: type: string maxLength: 100 description: A collection of user-defined key-value pairs that store custom metadata against the company. required: - id - name - redirect companyReference: title: Company reference type: object properties: id: $ref: '#/components/parameters/companyId/schema' name: $ref: '#/components/schemas/Company/definitions/companyDetails/properties/name' description: $ref: '#/components/schemas/Company/definitions/companyDetails/properties/description' links: type: object description: A collection of links for the company. properties: portal: type: string format: uri description: Link to the company page in the portal. tags: $ref: '#/components/schemas/Company/definitions/companyDetails/properties/tags' examples: - id: 0498e921-9b53-4396-a412-4f2f5983b0a2 name: string redirect: 'https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739' lastSync: '2022-01-01T12:00:00.000Z' created: '2022-01-01T12:00:00.000Z' createdByUserName: string tags: region: us uid: f6b0c253-16c7-4da1-a0c5-9c871e9c9d6c dataConnections: - id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c integrationKey: dfxm sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee platformName: Basiq linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start' status: Linked lastSync: '2022-10-27T10:22:43.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking CompanyInformation: title: Company information type: object description: Gets the latest basic info for a company. properties: companyName: type: string nullable: true description: Name of the linked company. baseCurrency: type: string nullable: true description: Currency set in the accounting software of the linked company. Used by the currency rate. CompanyRequestBody: title: Create company request x-internal: true type: object properties: name: type: string description: Name of company being connected. pattern: '^[A-Za-z0-9\s\-'',&@.,?!\s]+$' minLength: 1 example: Bank of Dave description: type: string example: Requested early access to the new financing scheme. description: 'Additional information about the company. This can be used to store foreign IDs, references, etc.' tags: $ref: '#/components/schemas/Company/definitions/companyDetails/properties/tags' required: - name Connection: title: Connection description: "\uFEFFA connection represents a [company's](https://docs.codat.io/sync-for-payables-api#/schemas/Company) connection to a data source and allows you to synchronize data (pull and/or push) with that source.\n\nA company can have multiple data connections depending on the type of data source it is connecting to. For example, a single company can link to:\n\n- [Accounting data](https://docs.codat.io/accounting-api/overview) - 1 active connection.\n- [Banking data](https://docs.codat.io/banking-api/overview) - Multiple active connections.\n- [Commerce data](https://docs.codat.io/commerce-api/overview) - Multiple active connections.\nAny combination of accounting, banking, and commerce data connections is allowed.\n\nBefore you can use a data connection to pull or push data, the company must grant you access to their business data by [linking the connection](https://docs.codat.io/auth-flow/overview)." type: object properties: id: $ref: '#/components/parameters/connectionId/schema' integrationId: type: string format: uuid example: fd321cb6-7963-4506-b873-e99593a45e30 description: A Codat ID representing the integration. integrationKey: type: string description: A unique four-character ID that identifies the platform of the company's data connection. This ensures continuity if the platform changes its name in the future. sourceId: type: string format: uuid example: 35b92968-9851-4095-ad60-395c95cbcba4 description: 'A source-specific ID used to distinguish between different sources originating from the same data connection. In general, a data connection is a single data source. However, for TrueLayer, `sourceId` is associated with a specific bank and has a many-to-one relationship with the `integrationId`.' sourceType: title: Source Type description: The type of platform of the connection. type: string enum: - Accounting - Banking - BankFeed - Commerce - Expense - Other - Unknown example: Accounting platformName: type: string description: Name of integration connected to company. linkUrl: type: string format: uri description: The link URL your customers can use to authorize access to their business application. example: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/2e2eb431-c1fa-4dc9-93fa-d29781c12bcd/start' status: $ref: '#/components/schemas/Connection/definitions/dataConnectionStatus' lastSync: $ref: '#/components/schemas/Connection/properties/created' nullable: true created: title: Date time type: string examples: - 2022-10-23T00:00:00.000Z - 2022-10-23T00:00:00.000Z description: |- In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example: ``` 2020-10-08T22:40:50Z 2021-01-01T00:00:00 ``` When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information: - Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z` - Unqualified local time: `2021-11-15T01:00:00` - UTC time offsets: `2021-11-15T01:00:00-05:00` > Time zones > > Not all dates from Codat will contain information about time zones. > Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced. dataConnectionErrors: type: array nullable: true items: $ref: '#/components/schemas/Connection/definitions/dataConnectionError' connectionInfo: type: object nullable: true additionalProperties: type: string additionalProperties: false required: - id - integrationId - integrationKey - sourceId - platformName - linkUrl - status - created - sourceType definitions: dataConnectionStatus: title: Data connection status description: The current authorization status of the data connection. type: string enum: - PendingAuth - Linked - Unlinked - Deauthorized dataConnectionError: title: Data connection error type: object properties: statusCode: type: string description: The HTTP status code returned by the source platform when the error occurred. statusText: type: string description: A non-numeric status code/text returned by the source platform when the error occurred. errorMessage: type: string description: A message about a error returned by Codat. erroredOnUtc: $ref: '#/components/schemas/Connection/properties/created' status: title: Error status description: The current status of a transient error. Null statuses indicate that the error is not transient. type: string nullable: true enum: - Active - Resolved resolvedOnUtc: description: The datetime in Utc that the error was resolved. nullable: true $ref: '#/components/schemas/Connection/properties/created' dataConnectionSourceType: title: Source Type description: The type of platform of the connection. type: string enum: - Accounting - Banking - BankFeed - Commerce - Expense - Other - Unknown example: Accounting example: id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c integrationKey: dfxm sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee platformName: Basiq linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start' status: Linked lastSync: '2022-10-27T10:22:43.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking Connections: title: Connections x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/Connection' - $ref: '#/components/schemas/PagingInfo' DataStatus: title: Data status description: Describes the state of data in the Codat cache for a company and data type type: object required: - dataType - lastSuccessfulSync - currentStatus properties: dataType: title: Data types x-internal: true type: string description: Available data types enum: - accountTransactions - balanceSheet - bankAccounts - bankTransactions - billCreditNotes - billPayments - bills - cashFlowStatement - chartOfAccounts - company - creditNotes - customers - directCosts - directIncomes - invoices - itemReceipts - items - journalEntries - journals - paymentMethods - payments - profitAndLoss - purchaseOrders - salesOrders - suppliers - taxRates - trackingCategories - transfers - banking-accountBalances - banking-accounts - banking-transactionCategories - banking-transactions - commerce-companyInfo - commerce-customers - commerce-disputes - commerce-locations - commerce-orders - commerce-paymentMethods - commerce-payments - commerce-productCategories - commerce-products - commerce-taxComponents - commerce-transactions example: invoices lastSuccessfulSync: $ref: '#/components/schemas/Connection/properties/created' currentStatus: $ref: '#/components/schemas/PullOperation/properties/status' latestSyncId: type: string description: Unique identifier for most recent sync of data type. format: uuid example: ad474a37-2003-478e-baee-9af9f1ec2fe3 latestSuccessfulSyncId: type: string description: Unique identifier for the most recent successful sync of data type. format: uuid example: 8220fc90-55b6-47bc-9417-48ac6ea93101 examples: - dataType: string lastSuccessfulSync: '2022-01-01T13:00:00.000Z' currentStatus: string latestSyncId: ad474a37-2003-478e-baee-9af9f1ec2fe3 latestSuccessfulSyncId: 8220fc90-55b6-47bc-9417-48ac6ea93101 DataType: x-internal: true $ref: '#/components/schemas/DataStatus/properties/dataType' ErrorMessage: title: Error message type: object x-internal: true properties: statusCode: type: integer description: The HTTP status code returned by the error. service: type: string description: Codat's service the returned the error. error: type: string description: A brief description of the error. correlationId: type: string description: Unique identifier used to propagate to all downstream services and determine the source of the error. validation: $ref: '#/components/schemas/ErrorMessage/definitions/errorValidation' canBeRetried: type: string description: '`True` if the error occurred transiently and can be retried.' detailedErrorCode: type: integer description: Machine readable error code used to automate processes based on the code returned. definitions: errorValidation: title: Validation error type: object nullable: true description: 'A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.' properties: errors: type: array nullable: true items: $ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem' warnings: type: array nullable: true items: $ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem' errorValidationItem: title: Validation error item type: object properties: itemId: type: string nullable: true description: Unique identifier for a validation item. message: type: string nullable: true description: A message outlining validation item's issue. validatorName: type: string nullable: true description: Name of validator. Pagination: title: Pagination metadata x-internal: true type: object properties: continuationToken: type: string description: 'A continuation token indicating there are more results to be fetched. Supply this value in the `continuationToken` query parameter in the next request to fetch the next set of results. Once no more results are available, the continuation token will not be present in the response.' PagingInfo: type: object title: Pagination information x-internal: true properties: pageNumber: type: integer description: Current page number. pageSize: type: integer description: Number of items to return in results array. maximum: 2000 totalResults: type: integer description: Total number of items. _links: $ref: '#/components/schemas/PagingInfo/definitions/links' definitions: links: title: Hal Links type: object required: - self - current properties: self: $ref: '#/components/schemas/PagingInfo/definitions/halRef' current: $ref: '#/components/schemas/PagingInfo/definitions/halRef' next: $ref: '#/components/schemas/PagingInfo/definitions/halRef' previous: $ref: '#/components/schemas/PagingInfo/definitions/halRef' examples: - self: href: /companies current: href: /companies?page=1&pageSize=10 halRef: title: Hypertext reference type: object properties: href: type: string format: uri-reference description: Uri hypertext reference. required: - pageNumber - pageSize - totalResults - _links examples: - pageNumber: 1 pageSize: 10 totalResults: 1 _links: self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' PaymentMappingOptions: x-internal: true title: Mapping Options Payments description: Gets the bill payments mapping options for a company's accounting software type: object properties: bankAccounts: type: array items: $ref: '#/components/schemas/PaymentMappingOptions/definitions/bankAccountMappingOption' pagination: $ref: '#/components/schemas/Pagination' definitions: bankAccountMappingOption: title: Bank account mapping option type: object allOf: - properties: id: type: string description: 'Identifier for the account, unique for the company in the accounting software.' example: 3d5a8e00-d108-4045-8823-7f342676cffa name: type: string nullable: true description: Name of the bank account in the accounting software. example: Bank of Dave current account accountNumber: type: string nullable: true description: |- Account number for the bank account. Xero integrations Only a UK account number shows for bank accounts with GBP currency and a combined total of sort code and account number that equals 14 digits, For non-GBP accounts, the full bank account number is populated. nominalCode: type: string nullable: true description: Code used to identify each nominal account for a business. sortCode: type: string nullable: true description: |- Sort code for the bank account. Xero integrations The sort code is only displayed when the currency = GBP and the sort code and account number sum to 14 digits. For non-GBP accounts, this field is not populated. currency: type: string nullable: true description: The bank account's base currency. status: $ref: '#/components/schemas/PaymentMappingOptions/definitions/bankAccountStatus' accountType: $ref: '#/components/schemas/BankAccount/allOf/0/properties/accountType' - $ref: '#/components/schemas/Attachment/allOf/1' bankAccountStatus: type: string description: The current status of the bank account. enum: - Active - Archived example: Active PullOperation: title: Pull operation description: |- Information about a queued, in progress or completed pull operation. *Formally called `dataset`* type: object properties: id: type: string format: uuid description: Unique identifier of the pull operation. example: 943accd0-4247-42d8-865b-363c8629e1da companyId: type: string format: uuid description: Unique identifier of the company associated to this pull operation. example: 22ece347-e5f6-4896-95e0-35a4c7f17023 connectionId: type: string format: uuid description: Unique identifier of the connection associated to this pull operation. example: 50830828-7d39-4367-b0eb-5ddb2de5faa5 dataType: title: Data types x-internal: true type: string description: The data type you are requesting in a pull operation. status: title: Dataset status type: string description: The current status of the dataset. enum: - Initial - Queued - Fetching - MapQueued - Mapping - Complete - FetchError - MapError - InternalError - ProcessingQueued - Processing - ProcessingError - ValidationQueued - Validating - ValidationError - AuthError - Cancelled - NotSupported - RateLimitError - PermissionsError - PrerequisiteNotMet statusDescription: type: string nullable: true description: Additional information about the dataset status. example: 'Paused until 2022-10-23T00:00:00.000Z' errorMessage: type: string nullable: true description: A message about a transient or persistent error returned by Codat or the source platform. requested: $ref: '#/components/schemas/Connection/properties/created' completed: $ref: '#/components/schemas/Connection/properties/created' progress: type: integer description: An integer signifying the progress of the pull operation. isCompleted: type: boolean description: '`True` if the pull operation is completed successfully. The `isCompleted` property is not queryable. To filter failed pull operations, query by `status!=Complete&&status!=NotSupported` instead.' isErrored: type: boolean description: '`True` if the pull operation entered an error state.' required: - id - companyId - connectionId - dataType - status - requested - progress - isCompleted - isErrored examples: - id: 97d60846-f07a-4d42-b5a0-0bdcc6ebf56b companyId: 4645bd78-8988-45bc-ac9e-67ba5df6e4e5 connectionId: 51baa045-4836-4317-a42e-3542e991e581 dataType: invoices status: Initial statusDescription: 'Paused until 2022-10-23T00:00:00.000Z' requested: '2022-11-14T11:18:37.2798351Z' progress: 10 isCompleted: false isErrored: false PullOperations: title: Pull operations x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/PullOperation' - $ref: '#/components/schemas/PagingInfo' PushOperation: title: Push operation type: object x-internal: true properties: changes: type: array nullable: true description: 'Contains a single entry that communicates which record has changed and the manner in which it changed. ' items: $ref: '#/components/schemas/PushOperation/definitions/pushOperationChange' dataType: $ref: '#/components/schemas/DataStatus/properties/dataType' description: 'The type of data being pushed, eg invoices, customers.' companyId: $ref: '#/components/parameters/companyId/schema' pushOperationKey: type: string format: uuid description: 'A unique identifier generated by Codat to represent this single push operation. This identifier can be used to track the status of the push, and should be persisted.' dataConnectionKey: $ref: '#/components/parameters/connectionId/schema' requestedOnUtc: $ref: '#/components/schemas/Connection/properties/created' description: The datetime when the push was requested. completedOnUtc: $ref: '#/components/schemas/Connection/properties/created' description: 'The datetime when the push was completed, null if Pending.' timeoutInMinutes: type: integer format: int32 nullable: true description: Number of minutes the push operation must complete within before it times out. timeoutInSeconds: type: integer format: int32 nullable: true deprecated: true description: Number of seconds the push operation must complete within before it times out. status: $ref: '#/components/schemas/PushOperation/definitions/pushOperationStatus' errorMessage: type: string nullable: true description: A message about the error. validation: $ref: '#/components/schemas/PushOperation/definitions/validation' statusCode: type: integer description: Push status code. required: - companyId - pushOperationKey - dataConnectionKey - requestedOnUtc - status - statusCode definitions: validation: type: object title: Validation description: 'A human-readable object describing validation decisions Codat has made when pushing data into the platform. If a push has failed because of validation errors, they will be detailed here.' properties: errors: type: array nullable: true items: $ref: '#/components/schemas/PushOperation/definitions/validationItem' warnings: type: array nullable: true items: $ref: '#/components/schemas/PushOperation/definitions/validationItem' validationItem: title: Validation item type: object properties: itemId: type: string nullable: true description: Unique identifier for a validation item. message: type: string nullable: true description: A message outlining validation item's issue. validatorName: type: string nullable: true description: Name of validator. additionalProperties: false pushChangeType: title: Push change type description: Type of change being applied to record in third party platform. type: string enum: - Unknown - Created - Modified - Deleted - AttachmentUploaded pushOperationRef: title: Push operation reference x-internal: true type: object properties: id: type: string description: Unique identifier for a push operation. dataType: $ref: '#/components/schemas/DataStatus/properties/dataType' nullable: true additionalProperties: false pushOperationStatus: title: Push operation status type: string enum: - Pending - Failed - Success - TimedOut description: The current status of the push operation. pushOperationChange: type: object properties: type: $ref: '#/components/schemas/PushOperation/definitions/pushChangeType' recordRef: $ref: '#/components/schemas/PushOperation/definitions/pushOperationRef' attachmentId: type: string description: Unique identifier for the attachment created otherwise null. nullable: true PushOperations: title: Push operations x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/PushOperation' - $ref: '#/components/schemas/PagingInfo' Supplier: title: Supplier description: "\uFEFFSuppliers are people or organizations that provide something, such as a product or service. Use the [List suppliers](https://docs.codat.io/sync-for-payables-v2-api#/operations/list-suppliers) endpoint to retrieve a list of all suppliers for a company.\n\nSuppliers' data links to accounts payable [bills](https://docs.codat.io/sync-for-payables-v2-api#/schemas/Bill).\n " type: object properties: id: type: string description: 'Identifier for the supplier, unique to the company in the accounting software.' supplierName: type: string description: 'Name of the supplier as recorded in the accounting system, typically the company name.' contactName: type: string nullable: true description: Name of the main contact for the supplier. emailAddress: type: string nullable: true description: Email address that the supplier may be contacted on. phone: type: string nullable: true description: Phone number that the supplier may be contacted on. examples: - +44 25691 154789 - (877) 492-8687 - 01224 658 999 addresses: type: array nullable: true description: An array of Addresses. items: $ref: '#/components/schemas/Address' status: $ref: '#/components/schemas/Supplier/definitions/supplierStatus' balance: type: number format: decimal nullable: true description: Amount outstanding against the supplier. defaultCurrency: type: string nullable: true description: Default currency the supplier's transactional data is recorded in. sourceModifiedDate: allOf: - $ref: '#/components/schemas/Connection/properties/created' - description: |- The date when a record was last modified in the source platform, usually by the business or a business process. For example, when payments are made against an invoice. It is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when: - Pulling attachments - The integration platform does not provide modification dates for a data type - A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred - A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records In Codat's data model, dates and times are represented using the ISO 8601 standard. definitions: supplierPrototype: title: Supplier prototype type: object properties: supplierName: $ref: '#/components/schemas/Supplier/properties/supplierName' contactName: $ref: '#/components/schemas/Supplier/properties/contactName' emailAddress: $ref: '#/components/schemas/Supplier/properties/emailAddress' phone: $ref: '#/components/schemas/Supplier/properties/phone' addresses: $ref: '#/components/schemas/Supplier/properties/addresses' status: $ref: '#/components/schemas/Supplier/definitions/supplierStatus' balance: $ref: '#/components/schemas/Supplier/properties/balance' defaultCurrency: $ref: '#/components/schemas/Supplier/properties/defaultCurrency' required: - supplierName - status supplierRef: title: Supplier reference description: Reference to the supplier the record relates to. type: object properties: id: minLength: 1 type: string description: The supplier's unique ID supplierName: type: string nullable: true description: The supplier's name required: - id supplierStatus: description: Status of the supplier. type: string enum: - Unknown - Active - Archived suppliers: title: Suppliers type: object properties: results: type: array items: $ref: '#/components/schemas/Supplier' pagination: $ref: '#/components/schemas/Pagination' examples: - id: C520FFD4-F6F6-4FC2-A6D2-5D7088B2B14F supplierName: Kelly's Industrial Supplies contactName: Kelly Ipsum emailAddress: sales@kellysupplies.com phone: 07999 999999 addresses: - type: Billing line1: Unit 51 line2: Bakersfield Industrial Estate city: Bakersfield region: California country: USA postalcode: '93308' status: Active amount: 100 defaultCurrency: GBP sourceModifiedDate: '2022-10-23T00:00:00Z' parameters: attachmentId: name: attachmentId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for an attachment. page: name: page in: query schema: type: integer format: int32 minimum: 1 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' pageSize: name: pageSize in: query schema: type: integer format: int32 default: 100 example: 100 minimum: 1 maximum: 5000 description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).' query: name: query in: query required: false schema: type: string example: id=e3334455-1aed-4e71-ab43-6bccf12092ee description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' orderBy: name: orderBy in: query required: false schema: type: string example: '-modifiedDate' description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).' billId: name: billId in: path required: true schema: type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ description: Unique identifier for a bill. companyId: name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. description: Unique identifier for a company. connectionId: name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. description: Unique identifier for a connection. continuationToken: name: continuationToken in: query required: false schema: type: string example: continuationToken=eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ== description: Retrieve the next page of results using the continuation token from the previous response. statusQuery: name: statusQuery in: query required: false schema: type: string example: status=Archived description: 'Codat query string allows you to filter by `status` (`status=Active||status=Archived`). [Learn more](https://docs.codat.io/using-the-api/querying) about Codat''s query string.' responses: BadRequest: description: The request made is not valid. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Malformed query: value: statusCode: 400 service: PublicApi error: Error processing request - not valid. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Malformed-Query: description: Your `query` parameter was not correctly formed content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Malformed query: value: statusCode: 400 service: ClientsApi error: Error parsing query - Malformed query. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Unresolved property: value: statusCode: 400 service: PullApi error: Error parsing query - Could not resolve property isCompleted on Dataset correlationId: 98457fb9956b7f9b4b2fd4f6e23bb5c8 canBeRetried: Unknown detailedErrorCode: 0 Unauthorized: description: Your API request was not properly authorized. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Unauthorized: value: statusCode: 401 service: PublicApi error: Unauthorized correlationId: 7eb40d6b415d7bcd99ce658268284056 canBeRetried: Unknown detailedErrorCode: 0 Payment-Required: description: | An account limit has been exceeded. The type of limit is described in the error property: - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 429 service: PublicApi error: You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Forbidden: description: You are using an outdated API key or a key not associated with that resource. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 403 service: PublicApi error: You are using an outdated API key or a key not associated with that resource. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Not-Found: description: |- One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Data connection not found: value: statusCode: 404 service: PublicApi error: Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found correlationId: 8fa2b5f4794970a4ee73758f612e8df0 canBeRetried: Unknown detailedErrorCode: 0 Company not found: value: statusCode: 404 service: ClientsApi error: No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e correlationId: 0a40c2f31fc8f992fb88b0853e4166f3 canBeRetried: Unknown detailedErrorCode: 0 No data available: value: statusCode: 404 service: PublicApi error: No data available for accounts for ID e5889b459f544926ac5b8e6756df2s correlationId: 0a40c2f31fc8f992fb88b0853e4166f3 canBeRetried: Unknown detailedErrorCode: 0 Conflict: description: The data type's dataset has not been requested or is still syncing. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 409 service: PublicApi error: The data set has not been requested. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Idempotency-Conflict: description: A request is in progress with the same idempotency key. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 409 service: PublicApi error: The data set has not been requested. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Too-Many-Requests: description: Too many requests were made in a given amount of time. Wait a short period and then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 429 service: PublicApi error: You have made too many requests in a given amount of time; please retry later. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Internal-Server-Error: description: There is a problem with our server. Please try again later. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 500 service: PublicApi error: There is a problem with our server. Please try again later. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Service-Unavailable: description: The Codat API is temporarily offline for maintenance. Please try again later. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 500 service: PublicApi error: The Codat API is temporarily offline for maintenance. Please try again later. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 securitySchemes: auth_header: name: Authorization description: 'The word "Basic" followed by a space and your API key. [API keys](https://docs.codat.io/sync-for-payables-api#/schemas/apiKeys) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/codat-api#/api-keys/api-keys-list), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.' type: apiKey in: header x-speakeasy-example: Basic BASE_64_ENCODED(API_KEY)