openapi: 3.1.0 info: title: Sync for Expenses (v1) version: prealpha contact: name: Codat url: 'https://www.codat.io/' email: expenses@codat.io description: |- The API for Sync for Expenses. Sync for Expenses is an API and a set of supporting tools. It has been built to enable corporate card and expense management platforms to provide high-quality integrations with multiple accounting software through a standardized API. ## Endpoints | Endpoints | Description | | :- |:- | | Connections | Create and manage partner expense connection. | | Configuration | Companies sync configuration. | | Mapping options | Mapping options for a companies expenses. | | Sync | Triggering a new sync of expenses to accounting software. | | Sync status | Check the status of ongoing or previous expense syncs. | | Expenses | Create expense datasets and upload receipts. | | Transaction status | Retrieve the status of transactions within a sync. | | Companies | Create and manage your Codat companies. | [Read more...](https://docs.codat.io/sync-for-expenses/overview) [See our OpenAPI spec](https://github.com/codatio/oas) Not seeing what you expect? [See the main Sync for Expenses API](https://docs.codat.io/sync-for-expenses-api). 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-codat-docs-path: sync-for-expenses-v1-api x-codat-speakeasy-pagination: type: offsetLimit inputs: - name: page in: parameters type: page outputs: results: $.results tags: - name: Connections description: Create and manage partner expense connection. - name: Configuration description: Companies sync configuration. - name: Mapping options description: Mapping options for a companies expenses. - name: Sync description: Triggering a new sync of expenses to accounting software. - name: Sync status description: Check the status of ongoing or previous expense syncs. - name: Expenses description: Create expense datasets and upload receipts. - name: Transaction status description: Retrieve the status of transactions within a sync. - name: Companies description: Create and manage your Codat companies. servers: - url: 'https://api.codat.io' paths: '/companies/{companyId}/sync/expenses/config': get: tags: - Configuration parameters: - $ref: '#/components/parameters/companyId' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanyConfiguration' examples: {} '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' summary: Get company configuration description: Gets a companies expense sync configuration operationId: get-company-configuration post: tags: - Configuration parameters: - $ref: '#/components/parameters/companyId' requestBody: content: application/json: schema: $ref: '#/components/schemas/CompanyConfiguration' examples: {} responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanyConfiguration' '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' summary: Set company configuration description: Sets a companies expense sync configuration operationId: save-company-configuration parameters: - $ref: '#/components/parameters/companyId' '/companies/{companyId}/sync/expenses/connections/partnerExpense': post: tags: - Connections description: Creates a partner expense data connection summary: Create partner expense connection operationId: create-partner-expense-connection parameters: - $ref: '#/components/parameters/companyId' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Connection' examples: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' '/companies/{companyId}/sync/expenses/mappingOptions': get: tags: - Mapping options parameters: - $ref: '#/components/parameters/companyId' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/MappingOptions' examples: {} '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' description: Gets the expense mapping options for a companies accounting software summary: Mapping options operationId: get-mapping-options parameters: - $ref: '#/components/parameters/companyId' '/companies/{companyId}/sync/expenses/syncs': post: tags: - Sync parameters: - $ref: '#/components/parameters/companyId' summary: Initiate sync description: Initiate sync of pending transactions. requestBody: content: application/json: schema: $ref: '#/components/schemas/PostSync' examples: {} responses: '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' '422': $ref: '#/components/responses/Unprocessable-Content' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' operationId: initiate-sync parameters: - $ref: '#/components/parameters/companyId' '/companies/{companyId}/sync/expenses/syncs/lastSuccessful/status': get: tags: - Sync status parameters: - $ref: '#/components/parameters/companyId' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanySyncStatus' examples: {} '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' description: Gets the status of the last successful sync summary: Last successful sync operationId: get-last-successful-sync parameters: - $ref: '#/components/parameters/companyId' '/companies/{companyId}/sync/expenses/syncs/latest/status': get: tags: - Sync status parameters: - $ref: '#/components/parameters/companyId' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanySyncStatus' examples: {} '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' description: Gets the latest sync status summary: Latest sync status operationId: get-latest-sync parameters: - $ref: '#/components/parameters/companyId' '/companies/{companyId}/sync/expenses/syncs/list/status': get: tags: - Sync status parameters: - $ref: '#/components/parameters/companyId' responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/CompanySyncStatus' examples: {} '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' summary: List sync statuses description: Gets a list of sync statuses operationId: list-syncs parameters: - $ref: '#/components/parameters/companyId' '/companies/{companyId}/sync/expenses/syncs/{syncId}/status': get: tags: - Sync status parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/syncId' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanySyncStatus' examples: {} '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' summary: Get sync status description: Get the sync status for a specified sync operationId: get-sync-by-id parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/syncId' '/companies/{companyId}/sync/expenses/syncs/{syncId}/transactions': get: parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/syncId' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/pageSize' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/TransactionMetadataList' examples: {} '400': $ref: '#/components/responses/Malformed-Query' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' tags: - Transaction status summary: Get sync transactions description: Get's the transactions and status for a sync operationId: list-sync-transactions parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/syncId' '/companies/{companyId}/sync/expenses/syncs/{syncId}/transactions/{transactionId}': get: parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/syncId' - $ref: '#/components/parameters/transactionId' responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/TransactionMetadata' examples: {} '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' tags: - Transaction status summary: Get sync transaction description: Gets the status of a transaction for a sync operationId: get-sync-transaction parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/syncId' - $ref: '#/components/parameters/transactionId' '/companies/{companyId}/sync/expenses/data/expense-transactions': parameters: - $ref: '#/components/parameters/companyId' post: summary: Create expense-transactions operationId: create-expense-dataset description: Create an expense transaction tags: - Expenses responses: '200': description: OK content: application/json: x-speakeasy-usage-example: true schema: $ref: '#/components/schemas/CreateExpenseResponse' examples: Example 1: value: datasetId: cd937d46-8e41-43a9-9477-a79158ffd98a '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' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateExpenseRequest' examples: Payment: value: items: - id: 4d7c6929-7770-412b-91bb-44d3bc71d111 type: Payment issueDate: '2021-05-21T00:00:00+00:00' currency: GBP currencyRate: 1.18 contactRef: id: f5244103-5223-4b0a-857f-50566ac86c11 type: Supplier merchantName: Amazon UK lines: - netAmount: 110.42 taxAmount: 14.43 taxRateRef: id: 77a32ee2-60c7-4ab9-917a-bd82e2e43a26 accountRef: id: 9aa5b894-1be9-4f97-96cd-ffde90766b3e trackingRefs: - id: dde5b35f-5d33-40bd-a34f-ee529f4c785c notes: 'APPLE.COM/BILL - 09001077498 - Card Ending: 4590' Refund: value: items: - id: 7008d3f2-aeb4-11ed-afa1-0242ac120002 type: Refund issueDate: '2023-02-17T00:00:00+00:00' currency: GBP merchantName: Amazon UK lines: - netAmount: 110.42 taxAmount: 14.43 taxRateRef: id: 23_Bills accountRef: id: '42' trackingRefs: - id: DEPARTMENT_6 notes: 'APPLE.COM/BILL - 09001077498 - Card Ending: 4590' Transfer: value: items: - id: 979a7ee8-aeb4-11ed-afa1-0242ac120002 type: TransferIn issueDate: '2021-05-21T00:00:00+00:00' currency: GBP lines: - netAmount: 180.93 taxAmount: 0 accountRef: id: 40e3e57c-2322-4898-966c-ca41adfd23fd notes: Credit Card Payment description: '' '/companies/{companyId}/sync/expenses/expense-transactions/{transactionId}': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/transactionId' put: summary: Update expense transactions tags: - Expenses responses: '202': description: Accepted content: application/json: schema: type: object properties: syncId: type: string description: Unique identifier for the updated sync. examples: Example 1: syncId: 1ad0695c-4566-4715-918c-adbb03eac81e '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' '422': $ref: '#/components/responses/Unprocessable-Content' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' operationId: update-expense-dataset description: Update an expense transaction requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateExpenseRequest' '/companies/{companyId}/sync/expenses/syncs/{syncId}/transactions/{transactionId}/attachments': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/syncId' - $ref: '#/components/parameters/transactionId' post: summary: Upload attachment operationId: upload-attachment tags: - Expenses description: Creates an attachment in the accounting software against the given transactionId requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/AttachmentUpload' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Attachment' examples: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' /companies: 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-expenses-v1-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-expenses-v1-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-expenses-v1-api#/schemas/Company) that represents your customer in Codat. \n\nA [company](https://docs.codat.io/sync-for-expenses-v1-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-expenses-v1-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-expenses-v1-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-expenses-v1-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-expenses-v1-api#/schemas/Company), its [connections](https://docs.codat.io/sync-for-expenses-v1-api#/schemas/Connection) and any cached data. This operation is irreversible.\n\nA [company](https://docs.codat.io/sync-for-expenses-v1-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-expenses-v1-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-expenses-v1-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-expenses-v1-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-expenses-v1-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: '' webhooks: expenses.sync.successful: post: description: Triggered when an expense sync successfully completes without any errors or warnings. requestBody: content: application/json: schema: $ref: '#/components/schemas/ExpensesSyncWebhook' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. expenses.sync.unsuccessful: post: description: 'Triggered when an expense sync fails to complete successfully, resulting in at least one error or warning.' requestBody: content: application/json: schema: $ref: '#/components/schemas/ExpensesSyncWebhook' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. SyncCompleted: post: deprecated: true description: |- Triggered anytime an expense sync completes. Used for Sync for Expenses only. > This event type is deprecated. Use the `expenses.sync.successful` to get notified when an expense sync completes successfully. requestBody: content: application/json: schema: $ref: '#/components/schemas/SyncCompleteWebhook' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. SyncFailed: post: deprecated: true description: |- Indicates a failure occurred during an expense sync. Used for Sync for Expenses only. > This event type is deprecated. Use the `expenses.sync.unsuccessful` to get notified when an expense sync completes unsuccessfully. requestBody: content: application/json: schema: $ref: '#/components/schemas/SyncFailedWebhook' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. components: schemas: AccountMappingInfo: title: Account mapping info type: object additionalProperties: false x-examples: Example AccountInfo: id: 313a4dbe-b3a4-42f0-a5f5-43e382e62db9 name: Travel currency: GBP accountType: Expense validTransactionTypes: - Payment - Refund properties: id: type: string description: Unique identifier of account. example: '6' nullable: true name: type: string description: Name of the account as it appears in the companies accounting software. example: Purchases nullable: true currency: type: string description: Currency of the account. example: GBP nullable: true accountType: type: string description: Type of the account. example: Expense enum: - Asset - Liability - Income - Expense - Equity nullable: true validTransactionTypes: type: array description: Supported transaction types for the account. minItems: 0 maxItems: 8 nullable: true items: type: string enum: - Payment - Refund - Reward - Chargeback - TransferIn - TransferOut - AdjustmentIn - AdjustmentOut example: Payment minLength: 1 maxLength: 8 Attachment: title: Attachment type: object x-examples: Attachment Example: companyId: bf1e0242-5b7a-418b-a307-9e09dbf9f39a id: '1400000000122699154' transactionId: f8f00edd-ddb0-4ca5-b36b-8f932e6b5160 properties: companyId: type: string format: uuid description: Unique ID of company in Codat id: type: string description: Unique identifier of attachment transactionId: type: string description: Unique identifier of transaction 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 account x-internal: true type: object properties: id: type: string description: The id of the account from which purchases are made example: '32' 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-expenses-v1-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 CompanyConfiguration: required: - bankAccount - supplier - customer title: Company configuration type: object x-examples: Config Example: bankAccount: id: '89' supplier: id: '124' customer: id: '140' properties: bankAccount: $ref: '#/components/schemas/BankAccount' supplier: $ref: '#/components/schemas/Supplier' customer: $ref: '#/components/schemas/Customer' CompanyRequestBody: title: Create company request x-internal: true type: object properties: name: type: string description: Name of company being connected. pattern: '^[A-Za-z0-9\s\-'',&@.,?!\s]+$' minLength: 1 example: Bank of Dave description: type: string example: Requested early access to the new financing scheme. description: 'Additional information about the company. This can be used to store foreign IDs, references, etc.' tags: $ref: '#/components/schemas/Company/definitions/companyDetails/properties/tags' required: - name CompanySyncStatus: title: Company sync status type: object additionalProperties: false x-examples: Success Data Pushed: companyId: 20803807-4e9a-4cb7-b67b-9f889a3916e1 syncId: aa4c9dfd-e945-4424-9628-9e724f14c267 syncStatusCode: 2000 syncStatus: Complete errorMessage: '' syncExceptionMessage: '' syncUtc: '2023-01-24T14:15:22Z' dataPushed: true Success No Data Pushed: companyId: 20803807-4e9a-4cb7-b67b-9f889a3916e1 syncId: aa4c9dfd-e945-4424-9628-9e724f14c267 syncStatusCode: 2040 syncStatus: Complete errorMessage: '' syncExceptionMessage: '' syncUtc: '2023-01-24T14:15:22Z' dataPushed: false properties: companyId: type: string description: Unique identifier for your SMB in Codat. example: d4d73051-ed31-42b6-99f6-d288cd940992 nullable: true syncId: type: string description: Unique identifier of the sync. example: a6a22aff-a43a-411d-a910-2dae73217cce nullable: true syncStatusCode: type: integer format: int32 description: Status code of the sync. example: 2000 syncStatus: type: string description: Text status of the sync. example: Completed nullable: true errorMessage: type: string description: Error message of the sync. nullable: true syncExceptionMessage: type: string description: Exception message of the sync. nullable: true syncUtc: $ref: '#/components/schemas/Connection/properties/created' description: Datetime of the sync. nullable: true dataPushed: type: boolean description: Boolean of whether the sync resulted in data being pushed. Connection: title: Connection description: "\uFEFFA connection represents a [company's](https://docs.codat.io/sync-for-expenses-v1-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' ContactRef: type: object title: Supplier/customer reference properties: id: type: string example: 40e3e57c-2322-4898-966c-ca41adfd23fd description: Identifier of supplier or customer. contactType: description: The type of contact. type: string example: Supplier enum: - Supplier CreateExpenseRequest: title: Create expense request x-internal: true type: object properties: items: type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/ExpenseTransaction' CreateExpenseResponse: title: Create expense response x-internal: true type: object properties: datasetId: type: string example: cd937d46-8e41-43a9-9477-a79158ffd98a format: uuid description: Unique id of dataset created Customer: title: Customer x-internal: true type: object properties: id: type: string description: id of the customer for all income related activities to be associated to. example: '142' DataConnection: $ref: '#/components/schemas/Connection' 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. ExpensesSyncWebhook: title: Expenses sync webhook type: object properties: id: type: string format: uuid example: ba29118f-5406-4e59-b05c-ba307ca38d01 description: Unique identifier of the event. eventType: type: string description: The type of event. examples: - expenses.sync.successful - expenses.sync.unsuccessful generatedDate: $ref: '#/components/schemas/Connection/properties/created' description: The date time in UTC the event was generated in Codat. payload: $ref: '#/components/schemas/ExpensesSyncWebhook/definitions/expensesSyncWebhookPayload' definitions: transaction: title: Transaction type: object properties: id: type: string description: Unique identifier of the transaction. status: type: string enum: - Unknown - PushError - Completed - Failed - Pending description: Status of transaction. errorMessage: type: string nullable: true description: Error message for failed transaction. expensesSyncWebhookPayload: title: Expenses sync webhook payload type: object properties: referenceCompany: $ref: '#/components/schemas/Company/definitions/companyReference' syncId: type: string description: Unique identifier of the sync. transactions: type: array items: $ref: '#/components/schemas/ExpensesSyncWebhook/definitions/transaction' ExpenseTransaction: title: Expense transaction type: object x-examples: Payment: id: a44135b0-6882-489a-83fe-a0c57a4afb19 type: Payment issueDate: '2021-05-21T00:00:00+00:00' currency: GBP currencyRate: 1.18 merchantName: Amazon UK lines: - netAmount: 110.42 taxAmount: 14.43 taxRateRef: id: 7e2ccb60-de1a-4c2b-9bd9-2f98a1c6be3f accountRef: id: a505cb47-0f7d-4e8b-90aa-9f9c2308b7bc trackingRefs: - id: 31a7e93c-4bb2-474c-b26d-10b2b75f7a25 notes: amazon purchase properties: id: type: string example: 4d7c6929-7770-412b-91bb-44d3bc71d111 format: uuid description: Your unique identifier for the transaction. type: type: string example: Payment description: The type of transaction. enum: - Payment - Refund - Reward - Chargeback - TransferIn - TransferOut - AdjustmentIn - AdjustmentOut issueDate: $ref: '#/components/schemas/Connection/properties/created' description: Date of the transaction was recorded. currency: type: string example: GBP description: Currency the transaction was recorded in. 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. | contactRef: description: Supplier or customer for the purchase to be associated to. $ref: '#/components/schemas/ContactRef' merchantName: type: string example: Amazon UK description: Name of the merchant where the purchase took place lines: type: array description: Array of transaction lines. minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/ExpenseTransactionLine' notes: type: string description: 'Any private, company notes about the transaction.' example: 'APPLE.COM/BILL - 09001077498 - Card Ending: 4590' required: - id - type - issueDate - currency ExpenseTransactionLine: x-internal: true title: Expense transaction line type: object x-examples: ExpenseTransactionLine: netAmount: 110.42 taxAmount: 14.43 taxRateRef: id: 08d37c46-8d5d-441b-8bad-76286c43047e accountRef: id: 16989b16-96d4-401a-9054-f5c620c655a6 trackingRefs: - id: e9a1b63d-9ff0-40e7-8038-016354b987e6 properties: netAmount: type: number format: decimal example: 110.42 description: 'Amount of the line, exclusive of tax.' taxAmount: type: number format: decimal example: 14.43 description: Amount of tax for the line. taxRateRef: $ref: '#/components/schemas/RecordRef' accountRef: $ref: '#/components/schemas/RecordRef' trackingRefs: type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/RecordRef' required: - netAmount - taxAmount - accountRef IntegrationType: title: Integration type x-internal: true type: string description: Type of transaction that has been processed e.g. Expense or Bank Feed. enum: - expenses - bankfeeds default: expenses example: expenses nullable: true MappingOptions: title: Mapping options type: object additionalProperties: false x-examples: {} properties: expenseProvider: type: string description: Name of the expense integration. example: Partner Expense nullable: true accounts: type: array description: Array of available accounts for mapping. nullable: true items: $ref: '#/components/schemas/AccountMappingInfo' trackingCategories: type: array description: Array of available tracking categories for mapping. nullable: true items: $ref: '#/components/schemas/TrackingCategoryMappingInfo' taxRates: type: array description: Array of available tax rates for mapping. nullable: true items: $ref: '#/components/schemas/TaxRateMappingInfo' 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' PostSync: title: Post sync type: object properties: datasetIds: minItems: 1 type: array items: type: string format: uuid nullable: true additionalProperties: false RecordRef: x-internal: true type: object title: Record reference properties: id: type: string example: 40e3e57c-2322-4898-966c-ca41adfd23fd description: identifier of linked reference from mapping options. Supplier: title: Supplier x-internal: true type: object properties: id: type: string description: id of the supplier for all purchases to be associated to example: '124' SyncCompleteWebhook: title: Sync complete webhook x-internal: true description: Webhook request body used to notify that a sync has completed. type: object properties: ClientId: $ref: '#/components/schemas/SyncFailedWebhook/properties/ClientId' ClientName: $ref: '#/components/schemas/SyncFailedWebhook/properties/ClientName' CompanyId: $ref: '#/components/parameters/companyId/schema' RuleId: $ref: '#/components/schemas/SyncFailedWebhook/properties/RuleId' RuleType: $ref: '#/components/schemas/SyncFailedWebhook/properties/RuleType' AlertId: $ref: '#/components/schemas/SyncFailedWebhook/properties/AlertId' Message: $ref: '#/components/schemas/SyncFailedWebhook/properties/Message' Data: $ref: '#/components/schemas/SyncCompleteWebhook/definitions/SyncCompleteWebhookData' definitions: SyncCompleteWebhookData: type: object title: Sync complete webhook data properties: syncId: $ref: '#/components/schemas/SyncFailedWebhook/definitions/SyncFailedWebhookData/properties/syncId' syncType: $ref: '#/components/schemas/SyncFailedWebhook/definitions/SyncFailedWebhookData/properties/syncType' examples: - ClientId: 30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e ClientName: Expense Sync CompanyId: 1f9559e7-8368-48c9-bdf4-f158e16b8b85 AlertId: 33a4f8e9-09ae-4334-9b00-7bbe83024672 RuleId: 5c27631d-3b63-4b50-8228-ee502fd113eb RuleType: Sync Completed Message: Sync 321363b4-efa9-4fbc-b71c-0b58d62f3248 for company 1f9559e7-8368-48c9-bdf4-f158e16b8b85 of type Expense completed successfully. Data: syncId: 321363b4-efa9-4fbc-b71c-0b58d62f3248 syncType: Expense SyncFailedWebhook: title: Sync failed webhook x-internal: true description: Webhook request body used to notify that a sync has failed. 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. CompanyId: $ref: '#/components/parameters/companyId/schema' RuleId: type: string format: uuid description: Unique identifier for the rule. deprecated: true RuleType: type: string x-stoplight: id: 34d52a089f08a description: The type of rule. AlertId: type: string format: uuid description: Unique identifier of the webhook event. Message: type: string description: A human-readable message about the webhook. Data: $ref: '#/components/schemas/SyncFailedWebhook/definitions/SyncFailedWebhookData' definitions: SyncFailedWebhookData: type: object title: Sync failed webhook data properties: syncId: type: string format: uuid example: a9367074-b5c3-42c4-9be4-be129f43577e description: Unique identifier for the failed sync. syncType: type: string description: The type of sync being performed. FailureStage: type: string description: The stage of the job the sync failed. examples: - ClientId: 30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e ClientName: Expense Sync CompanyId: 1f9559e7-8368-48c9-bdf4-f158e16b8b85 RuleId: 289c80dc-2aee-4b71-afff-9acd8d051080 RuleType: Sync Failed AlertId: 72c1103b-7f17-4a3a-8db5-67c2d360a516 Message: Sync 3bead2a1-1b3d-4d90-8077-cddc5ca68b01 for company 1f9559e7-8368-48c9-bdf4-f158e16b8b85 of type Expense has failed at step Pushing. Data: syncId: 3bead2a1-1b3d-4d90-8077-cddc5ca68b01 syncType: Expense FailureStage: Pushing SyncInitiated: title: Sync initiated type: object properties: syncId: type: string format: uuid description: Unique identifier for the initiated sync. additionalProperties: false TaxRateMappingInfo: title: Tax rate mapping info type: object additionalProperties: false x-examples: UK Tax Rate: id: 59_Bills name: UK Standard Rate (Bills) Bills code: UK Standard Rate (Bills) effectiveTaxRate: 20 totalTaxRate: 20 validTransactionTypes: - Payment - Reward properties: id: type: string description: Unique identifier of tax rate. example: 59_Bills nullable: true name: type: string description: Name of the tax rate in the accounting software. example: UK Standard Rate (Bills) Bills nullable: true code: type: string description: Code for the tax rate from the accounting software. example: UK Standard Rate (Bills) nullable: true effectiveTaxRate: type: number format: decimal description: Effective tax rate. example: 20 totalTaxRate: type: number format: decimal description: Total (not compounded) sum of the components of a tax rate. example: 20 validTransactionTypes: type: array description: Supported transaction types for the account. minItems: 0 maxItems: 8 nullable: true items: type: string enum: - Payment - Refund - Reward - Chargeback - TransferIn - TransferOut - AdjustmentIn - AdjustmentOut example: Payment TrackingCategoryMappingInfo: title: Tracking category mapping info type: object additionalProperties: false x-examples: Tracking Category with parentId: id: DEPARTMENT_1 modifiedDate: '2023-02-09T11:42:41Z' name: TestLocation hasChildren: false parentId: DEPARTMENTS Parent Tracking Category: id: DEPARTMENTS modifiedDate: '2023-02-09T11:42:41Z' name: Departments hasChildren: true properties: id: type: string description: Unique identifier of the tracking category. example: DEPARTMENT_2 nullable: true modifiedDate: $ref: '#/components/schemas/Connection/properties/created' description: Datetime when the tracking category was last modified. nullable: true name: type: string description: Name of the tracking category as it appears in the accounting software. example: New York nullable: true hasChildren: type: boolean description: Boolean of whether the tracking category has child categories. parentId: type: string description: ID of the parent tracking category example: DEPARTMENTS nullable: true TransactionMetadata: title: Transaction metadata type: object additionalProperties: false x-examples: Successful Transaction: transactionId: 8fdba4ed-e327-4925-be1a-b7a2b04627f7 status: Completed integrationType: expense Unsuccessful Transaction: transactionId: 3d694cd1-4cd9-4136-91db-32408195c6fc status: ValidationError message: The line item total -208.10((-195.01 + -1.09) + (-10.01 + -1.99)) must equal the transaction total -1.1 integrationType: string properties: transactionId: type: string description: Your unique idenfier of the transaction. example: aa02271d-ed5f-47f5-be76-778d5905225a nullable: true status: $ref: '#/components/schemas/TransactionStatus' message: type: string description: Metadata such as validation errors or the resulting record created in the accounting software. nullable: true integrationType: $ref: '#/components/schemas/IntegrationType' TransactionMetadataList: title: Transaction metadata list x-internal: true additionalProperties: false allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/TransactionMetadata' - $ref: '#/components/schemas/PagingInfo' x-examples: Example 1: results: - transactionId: aa02271d-ed5f-47f5-be76-778d5905225a status: Completed integrationType: expenses - transactionId: 730177a2-8505-410a-9ebc-c2dd52e4bea9 status: Completed integrationType: expenses pageNumber: 1 pageSize: 100 totalResults: 2 links: self: href: string current: href: string TransactionStatus: title: Transaction status x-internal: true type: string description: Status of the transaction. enum: - Unknown - Pending - ValidationError - Completed - PushError example: Completed nullable: true UpdateExpenseRequest: title: Updating Expense Transaction Request type: object examples: Payment: value: type: Payment issueDate: '2023-05-22T00:00:00+00:00' currency: GBP currencyRate: 1.18 notes: New notes contactRef: id: f5244103-5223-4b0a-857f-50566ac86c11 type: Supplier merchantName: My Merchant properties: type: '#/definitions/expenseType' issueDate: type: string description: Date the transaction was recorded. example: '2022-06-28T00:00:00.000Z' currency: type: string example: GBP description: Currency the transaction was recorded in. currencyRate: $ref: '#/components/schemas/ExpenseTransaction/properties/currencyRate' contactRef: description: Supplier or Customer for the purchase to be associated to. $ref: '#/components/schemas/ContactRef' merchantName: type: string description: Name of the merchant where the purchase took place example: Amazon UK lines: type: array description: Array of transaction lines. items: $ref: '#/components/schemas/ExpenseTransactionLine' notes: type: string description: 'Any private, company notes about the transaction.' example: 'APPLE.COM/BILL - 09001077498 - Card Ending: 4590' definitions: expenseType: description: The type of transaction. type: string example: Payment enum: - Payment - Refund - Reward - Chargeback - TransferIn - TransferOut - AdjustmentIn - AdjustmentOut required: - type - issueDate parameters: syncId: name: syncId in: path required: true schema: type: string format: uuid example: 6fb40d5e-b13e-11ed-afa1-0242ac120002 description: Unique identifier for a sync. transactionId: name: transactionId in: path required: true schema: type: string format: uuid example: 336694d8-2dca-4cb5-a28d-3ccb83e55eee description: The unique identifier for your SMB's transaction. 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).' 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. 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 Unprocessable-Content: description: The requests made can't be processed. This may be due to differences in platform support. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 422 service: ExpenseSyncApi error: Expense transaction updates are not supported for platforms other than Xero. correlationId: 7c8e23841d211c87f49f30b248f70c93 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/accounting-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)