{ "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.\nSync 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.\n\n[Read more...](https://docs.codat.io/sync-for-expenses/overview)\n\n[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": "A 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:\n\n```\n2020-10-08T22:40:50Z\n2021-01-01T00:00:00\n```\n\n\n\nWhen syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:\n\n- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`\n- Unqualified local time: `2021-11-15T01:00:00`\n- UTC time offsets: `2021-11-15T01:00:00-05:00`\n\n> Time zones\n> \n> Not all dates from Codat will contain information about time zones. \n> 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.\n\nCurrency rates in Codat are implemented as the multiple of foreign currency units to each base currency unit. \n\nIt 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.\n\nWhere 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). \n\nFor accounting platforms which do not provide an explicit currency rate, it is calculated as `baseCurrency / foreignCurrency` and will be returned to 9 decimal places.\n\n## Examples with base currency of GBP\n\n| Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (GBP) |\n| :--------------- | :------------- | :------------ | :------------------------- |\n| **USD** | $20 | 0.781 | £15.62 |\n| **EUR** | €20 | 0.885 | £17.70 |\n| **RUB** | ₽20 | 0.011 | £0.22 |\n\n## Examples with base currency of USD\n\n| Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (USD) |\n| :--------------- | :------------- | :------------ | :------------------------- |\n| **GBP** | £20 | 1.277 | $25.54 |\n| **EUR** | €20 | 1.134 | $22.68 |\n| **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.\nThis 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)" } } } }