openapi: 3.1.0 info: title: Sync for Expenses API 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 platforms through a standardized API. [Read more...](https://docs.codat.io/sync-for-expenses/overview) [See our OpenAPI spec](https://github.com/codatio/oas) 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 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. servers: - url: 'https://api.codat.io' paths: '/companies/{companyId}/sync/expenses/config': get: tags: - Configuration parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanyConfiguration' examples: {} '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' summary: Get company configuration description: Gets a companies expense sync configuration operationId: get-company-configuration post: tags: - Configuration parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' 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' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' summary: Set company configuration description: Sets a companies expense sync configuration operationId: save-company-configuration parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' '/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: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DataConnection' examples: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '/companies/{companyId}/sync/expenses/mappingOptions': get: tags: - Mapping options parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/MappingOptions' examples: {} '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' description: Gets the expense mapping options for a companies accounting software summary: Mapping options operationId: get-mapping-options parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' '/companies/{companyId}/sync/expenses/syncs': post: tags: - Sync parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' summary: Initiate sync description: Initiate sync of pending transactions. requestBody: content: application/json: schema: $ref: '#/components/schemas/PostSync' examples: {} responses: '202': description: Returns the newly created SyncId content: application/json: schema: $ref: '#/components/schemas/SyncInitiated' examples: {} '400': description: If model is incorrect content: application/json: schema: $ref: '#/components/schemas/CodatErrorMessage' '404': description: If company not found content: application/json: schema: $ref: '#/components/schemas/CodatErrorMessage' '422': description: If the specified company does not have a valid set of DataConnections setup content: application/json: schema: $ref: '#/components/schemas/CodatErrorMessage' operationId: intiate-sync parameters: - name: companyId in: path required: true schema: $ref: '#/components/schemas/SyncFailedWebhook/properties/CompanyId' '/companies/{companyId}/sync/expenses/syncs/lastSuccessful/status': get: tags: - Sync status parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanySyncStatus' examples: {} '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' description: Gets the status of the last successful sync summary: Last successful sync operationId: get-last-successful-sync parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' '/companies/{companyId}/sync/expenses/syncs/latest/status': get: tags: - Sync status parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanySyncStatus' examples: {} '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' description: Gets the latest sync status summary: Latest sync status operationId: get-latest-sync parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' '/companies/{companyId}/sync/expenses/syncs/list/status': get: tags: - Sync status parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/CompanySyncStatus' examples: {} '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' summary: List sync statuses description: Gets a list of sync statuses operationId: list-syncs parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' '/companies/{companyId}/sync/expenses/syncs/{syncId}/status': get: tags: - Sync status parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' - $ref: '#/components/parameters/syncId' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanySyncStatus' examples: {} '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' summary: Get Sync status description: Get the sync status for a specified sync operationId: get-sync-by-id parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' - $ref: '#/components/parameters/syncId' '/companies/{companyId}/sync/expenses/syncs/{syncId}/transactions': get: parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' - $ref: '#/components/parameters/syncId' - 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).' - 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).' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/TransactionMetadataList' examples: {} '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' tags: - Transaction status summary: Get Sync transactions description: Get's the transactions and status for a sync operationId: list-sync-transactions parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' - $ref: '#/components/parameters/syncId' '/companies/{companyId}/sync/expenses/syncs/{syncId}/transactions/{transactionId}': get: parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' - $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' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' tags: - Transaction status summary: Get Sync Transaction description: Gets the status of a transaction for a sync operationId: get-sync-transaction parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' - $ref: '#/components/parameters/syncId' - $ref: '#/components/parameters/transactionId' '/companies/{companyId}/sync/expenses/data/expense-transactions': parameters: - $ref: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' 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' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' 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: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' - $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 examples: Example 1: syncId: 1ad0695c-4566-4715-918c-adbb03eac81e '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '422': $ref: '#/components/responses/Unprocessable-Content' '429': $ref: '#/components/responses/Too-Many-Requests' 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: '#/paths/~1companies~1%7BcompanyId%7D~1sync~1expenses~1syncs/parameters/0' - $ref: '#/components/parameters/syncId' - $ref: '#/components/parameters/transactionId' post: summary: Upload attachment operationId: upload-attachment responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Attachment' examples: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' requestBody: content: multipart/form-data: schema: type: string format: binary tags: - Expenses description: Creates an attachment in the accounting software against the given transactionId webhooks: Sync Started: post: requestBody: description: Triggered anytime a sync starts. content: application/json: schema: $ref: '#/components/schemas/SyncStartedWebhook' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. Sync Failed: post: requestBody: description: Triggered anytime a sync fails. content: application/json: schema: $ref: '#/components/schemas/SyncFailedWebhook' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. Sync Complete: post: requestBody: description: Triggered anytime a sync completes. content: application/json: schema: $ref: '#/components/schemas/SyncCompleteWebhook' responses: '200': description: Return a 200 status to indicate that the webhook was received successfully. components: schemas: DataConnection: title: Connection description: "\uFEFFA connection represents a [company's](https://docs.codat.io/codat-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: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. 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 x-internal: true description: The type of platform of the connection. type: string enum: - Accounting - Banking - Commerce - Other - Unknown example: Accounting platformName: type: string linkUrl: type: string format: uri example: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/2e2eb431-c1fa-4dc9-93fa-d29781c12bcd/start' status: $ref: '#/components/schemas/DataConnection/definitions/dataConnectionStatus' lastSync: $ref: '#/components/schemas/DataConnection/properties/created' 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 items: $ref: '#/components/schemas/DataConnection/definitions/dataConnectionError' connectionInfo: type: object 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 statusText: type: string errorMessage: type: string erroredOnUtc: $ref: '#/components/schemas/DataConnection/properties/created' dataConnectionSourceType: title: Source Type description: The type of platform of the connection. type: string enum: - Accounting - Banking - Commerce - 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 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 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/DataConnection/properties/created' description: Datetime of the sync. nullable: true dataPushed: type: boolean description: Boolean of whether the sync resulted in data being pushed. 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' 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 platform. example: UK Standard Rate (Bills) Bills nullable: true code: type: string description: Code for the tax rate from the accounting platform. example: UK Standard Rate (Bills) nullable: true effectiveTaxRate: type: number description: Effective tax rate. example: 20 totalTaxRate: type: number 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/DataConnection/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' TransactionStatus: x-internal: true type: string description: Status of the transaction. enum: - Unknown - Pending - ValidationError - Completed - PushError example: Completed nullable: true IntegrationType: 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 TransactionMetadataList: 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 CreateExpenseRequest: x-internal: true type: object properties: items: type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/ExpenseTransaction' CreateExpenseResponse: x-internal: true type: object properties: datasetId: type: string example: cd937d46-8e41-43a9-9477-a79158ffd98a format: uuid description: Unique id of dataset created 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/DataConnection/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 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 platform, it will be available from Codat with the same precision (up to a maximum of 9 decimal places). For accounting platforms 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 | 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 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. 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 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 example: 110.42 description: 'Amount of the line, exclusive of tax.' taxAmount: type: number 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 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 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' BankAccount: x-internal: true type: object properties: id: type: string description: The id of the account from which purchases are made example: '32' Supplier: x-internal: true type: object properties: id: type: string description: id of the supplier for all purchases to be associated to example: '124' 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' SyncInitiated: title: Sync initiated type: object properties: syncId: type: string format: uuid additionalProperties: false PostSync: title: Post sync type: object properties: datasetIds: minItems: 1 type: array items: type: string format: uuid nullable: true additionalProperties: false CodatErrorMessage: title: Error message type: object properties: statusCode: type: integer service: type: string error: type: string correlationId: type: string validation: type: object properties: hasErrors: type: boolean hasWarnings: type: boolean hasInternals: type: boolean errors: type: array items: type: object properties: itemId: type: string message: type: string validatorName: type: string ruleId: type: string warnings: type: array items: type: object properties: itemId: type: string message: type: string validatorName: type: string ruleId: type: string internals: type: array items: type: object properties: itemId: type: string message: type: string validatorName: type: string ruleId: type: string inner: type: string canBeRetried: type: string detailedErrorCode: type: integer x-examples: Not Found: statusCode: 404 service: ExpenseSyncApi error: NotFound correlationId: '' canBeRetried: Unknown detailedErrorCode: 0 Invalid Dataset: statusCode: 400 service: ExpenseSyncApi error: 'There are problems with the request, see the Validation property for more detail.' correlationId: 2201579598a29055025d2e0f829fa89a validation: errors: - itemId: 'Items[0].Lines[0].NetAmount' message: The field NetAmount must be between 0 and 5000000. - itemId: 'Items[0].Lines[0].TaxAmount' message: The field TaxAmount must be between 0 and 5000000. warnings: [] canBeRetried: 'No' detailedErrorCode: 0 PagingInfo: type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: $ref: '#/components/schemas/HalLink' current: $ref: '#/components/schemas/HalLink' next: $ref: '#/components/schemas/HalLink' previous: $ref: '#/components/schemas/HalLink' examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' HalLink: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference 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: $ref: '#/components/schemas/UpdateExpenseRequest/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 SyncStartedWebhook: title: Sync started webhook x-internal: true description: Webhook request body used to notify that a sync has started. type: object properties: ClientId: $ref: '#/components/schemas/SyncFailedWebhook/properties/ClientId' ClientName: $ref: '#/components/schemas/SyncFailedWebhook/properties/ClientName' CompanyId: $ref: '#/components/schemas/SyncFailedWebhook/properties/CompanyId' 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: type: object properties: syncId: $ref: '#/components/schemas/SyncFailedWebhook/properties/Data/properties/syncId' syncType: $ref: '#/components/schemas/SyncFailedWebhook/properties/Data/properties/syncType' SyncDateRangeStartUtc: $ref: '#/components/schemas/SyncFailedWebhook/properties/Data/properties/SyncDateRangeStartUtc' SyncDateRangeFinishUtc: $ref: '#/components/schemas/SyncFailedWebhook/properties/Data/properties/SyncDateRangeFinishUtc' 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 Started Message: Sync 321363b4-efa9-4fbc-b71c-0b58d62f3248 for company 1f9559e7-8368-48c9-bdf4-f158e16b8b85 of type Expense has started. Data: syncId: 321363b4-efa9-4fbc-b71c-0b58d62f3248 syncType: Expense SyncDateRangeStartUtc: '2023-05-03T09:56:17.4357111Z' SyncDateRangeFinishUtc: '2023-05-03T09:56:18.4357111Z' SyncFailedWebhook: title: Sync failed webhook x-internal: true description: Webhook request body used to notify that a sync has failed. type: object properties: ClientId: type: string format: uuid description: Unique identifier for your client in Codat. ClientName: type: string description: Name of your client in Codat. CompanyId: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. RuleId: type: string format: uuid description: Unique identifier for the rule. 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: type: object properties: syncId: type: string format: uuid example: a9367074-b5c3-42c4-9be4-be129f43577e syncType: type: string description: The type of sync being performed. SyncDateRangeStartUtc: $ref: '#/components/schemas/DataConnection/properties/created' description: The start datetime data will be synced from. SyncDateRangeFinishUtc: $ref: '#/components/schemas/DataConnection/properties/created' description: The end datetime data will be synced to. 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 SyncDateRangeStartUtc: 2023-05-03T12:57:58.757Z SyncDateRangeFinishUtc: 2023-05-03T12:57:59.757Z FailureStage: Pushing 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/schemas/SyncFailedWebhook/properties/CompanyId' 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: type: object properties: syncId: $ref: '#/components/schemas/SyncFailedWebhook/properties/Data/properties/syncId' syncType: $ref: '#/components/schemas/SyncFailedWebhook/properties/Data/properties/syncType' SyncDateRangeStartUtc: $ref: '#/components/schemas/SyncFailedWebhook/properties/Data/properties/SyncDateRangeStartUtc' SyncDateRangeFinishUtc: $ref: '#/components/schemas/SyncFailedWebhook/properties/Data/properties/SyncDateRangeFinishUtc' 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 SyncDateRangeStartUtc: '2023-05-03T09:56:17.4357111Z' SyncDateRangeFinishUtc: '2023-05-03T09:56:18.4357111Z' ErrorMessage: type: object x-internal: true properties: statusCode: type: integer service: type: string error: type: string correlationId: type: string canBeRetried: type: string detailedErrorCode: type: integer 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. 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 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 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 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 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 securitySchemes: auth_header: name: Authorization description: 'The word "Basic" followed by a space and your API Key, base64 encoded, which can be found [here](https://app.codat.io/developers/api-keys)' type: apiKey in: header x-speakeasy-example: Basic BASE_64_ENCODED(API_KEY)