{ "openapi": "3.1.0", "x-stoplight": { "id": "v6f6vc930irb5" }, "servers": [ { "description": "Production", "url": "https://api.codat.io" } ], "info": { "title": "Sync for Commerce", "version": "1.1", "contact": { "name": "Codat", "url": "https://www.codat.io/", "email": "syncforcommerce@codat.io" }, "description": "The API for Sync for Commerce. \n\nSync for Commerce automatically replicates and reconciles sales data from a merchant’s source PoS, Payments, and eCommerce systems into their accounting software. This eliminates manual processing by merchants and transforms their ability to run and grow their business.\n \n[Explore product](https://docs.codat.io/commerce/overview) | [See our OpenAPI spec](https://github.com/codatio/oas)\n\nNot seeing the endpoints you're expecting? We've [reorganized our products](https://docs.codat.io/updates/230901-new-products), and you may be using a [different version of Sync for Commerce](https://docs.codat.io/sync-for-commerce-v1-api#/).\n\n---\n\n\n## Endpoints\n\n| Endpoints | Description |\n| :- |:- |\n| Connections | Create new and manage existing data connections for a company. |\n| Sync | Initiate data syncs and monitor their status. |\n| Sync flow settings | Control text and visibility settings for the Sync Flow. |\n| Integrations | Get a list of integrations supported by Sync for Commerce and their logos. |\n| Advanced controls | View and manage mapping configured for a company's commerce sync. |\n", "termsOfService": "https://www.codat.io/legals/" }, "security": [ { "auth_header": [] } ], "x-speakeasy-retries": { "strategy": "backoff", "backoff": { "initialInterval": 500, "maxInterval": 60000, "maxElapsedTime": 3600000, "exponent": 1.5 }, "statusCodes": [ 408, 429, "5XX" ], "retryConnectionErrors": true }, "x-speakeasy-name-override": [ { "operationId": "^list-.*?", "methodNameOverride": "list" }, { "operationId": "^list-.*?-attachments", "methodNameOverride": "list-attachments" }, { "operationId": "^get-.*?", "methodNameOverride": "get" }, { "operationId": "^get-create-.*?-model", "methodNameOverride": "get-create-model" }, { "operationId": "^get-create-update.*?-model", "methodNameOverride": "get-create-update-model" }, { "operationId": "^get-.*?-attachment", "methodNameOverride": "get-attachment" }, { "operationId": "^update-.*?", "methodNameOverride": "update" }, { "operationId": "^create-.*?", "methodNameOverride": "create" }, { "operationId": "^delete-.*?", "methodNameOverride": "delete" }, { "operationId": "^delete-.*?-attachment", "methodNameOverride": "delete-attachment" }, { "operationId": "^download-.*?-attachment", "methodNameOverride": "download-attachment" }, { "operationId": "^upload-.*?-attachment", "methodNameOverride": "upload-attachment" } ], "x-codat-docs-path": "sync-for-commerce-api", "x-codat-keep-docs-paths-local": true, "x-codat-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page", "in": "parameters", "type": "page" } ], "outputs": { "results": "$.results" } }, "tags": [ { "name": "Connections", "description": "Create new and manage existing data connections for a company." }, { "name": "Sync", "description": "Initiate data syncs and monitor their status." }, { "name": "Sync flow settings", "description": "Control text and visibility settings for the Sync Flow." }, { "name": "Integrations", "description": "Get a list of integrations supported by Sync for Commerce and their logos." }, { "name": "Advanced controls", "description": "View and manage mapping configured for a company's commerce sync." } ], "paths": { "/config/sync/commerce/{commerceKey}/{accountingKey}/start": { "get": { "tags": [ "Connections" ], "summary": "Start new sync flow", "description": "Create a new company and connections. Get a URL for Sync Flow, including a one time passcode.", "operationId": "get-sync-flow-url", "x-speakeasy-name-override": "get-sync-flow-url", "parameters": [ { "name": "commerceKey", "in": "path", "description": "Commerce platform key", "required": true, "schema": { "type": "string" } }, { "name": "accountingKey", "in": "path", "description": "Accounting platform key", "required": true, "schema": { "type": "string" } }, { "name": "merchantIdentifier", "in": "query", "schema": { "type": "string" }, "description": "Identifier for your merchant, can be the merchant name or Codat company id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncFlowUrl" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "parameters": [ { "schema": { "type": "string" }, "name": "commerceKey", "in": "path", "required": true, "description": "Unique identifier for commerce software." }, { "schema": { "type": "string" }, "name": "accountingKey", "in": "path", "required": true, "description": "Unique identifier for accounting software." } ] }, "/companies": { "get": { "tags": [ "Advanced controls" ], "summary": "List companies", "description": "Returns a list of companies.", "operationId": "list-companies", "x-speakeasy-name-override": "list-companies", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies" } } } }, "400": { "$ref": "#/components/responses/Malformed-Query" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "post": { "tags": [ "Advanced controls" ], "summary": "Create company", "description": "Creates a Codat company", "operationId": "create-company", "x-speakeasy-name-override": "create-company", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompany" }, "example": { "name": "string" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections": { "get": { "summary": "List connections", "description": "List the connections for a company.", "operationId": "list-connections", "tags": [ "Connections" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connections" }, "examples": { "Connections": { "value": { "results": [ { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } ], "pageNumber": 0, "pageSize": 0, "totalResults": 0, "_links": { "self": { "href": "string" }, "current": { "href": "string" }, "next": { "href": "string" }, "previous": { "href": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/Malformed-Query" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "post": { "summary": "Create connection", "description": "Creates a connection for the company by providing a valid `platformKey`. \n\nUse the [List Integrations](https://docs.codat.io/sync-for-sync-for-commerce-api#/operations/list-integrations) endpoint to access valid platform keys. ", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "tags": [ "Connections" ], "operationId": "create-connection", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platformKey": { "$ref": "#/components/parameters/platformKey/schema" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" }, "examples": { "Connection": { "value": { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}": { "patch": { "tags": [ "Connections" ], "summary": "Update connection", "description": "Update a data connection", "operationId": "update-connection", "x-speakeasy-name-override": "update-connection", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConnection" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ] }, "/companies/{companyId}/connections/{connectionId}/authorization": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "put": { "summary": "Update authorization", "operationId": "update-connection-authorization", "x-speakeasy-name-override": "update-authorization", "description": "Update data connection's authorization.", "tags": [ "Connections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } }, "description": "" } } }, "/config/companies/{companyId}/sync/commerce": { "get": { "tags": [ "Advanced controls" ], "summary": "Get company configuration", "description": "Returns a company's commerce sync configuration'.", "operationId": "get-configuration", "x-speakeasy-name-override": "get-configuration", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Configuration" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "post": { "tags": [ "Advanced controls" ], "summary": "Set configuration", "description": "Sets a company's commerce sync configuration.", "operationId": "set-configuration", "x-speakeasy-name-override": "set-configuration", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Configuration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/config/integrations": { "get": { "tags": [ "Integrations" ], "summary": "List integrations", "description": "Retrieve a list of available integrations support by data type and state of release.", "operationId": "list-integrations", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integrations" } } } }, "400": { "$ref": "#/components/responses/Malformed-Query" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/config/integrations/{platformKey}/branding": { "get": { "tags": [ "Integrations" ], "summary": "Get branding for an integration", "description": "Retrieve Integration branding assets.", "operationId": "get-integration-branding", "x-speakeasy-name-override": "get-branding", "parameters": [ { "$ref": "#/components/parameters/platformKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branding" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "parameters": [ { "schema": { "type": "string" }, "name": "platformKey", "in": "path", "required": true, "description": "Unique four letter identifier for the platform" } ] }, "/sync/commerce/config/ui/text": { "get": { "tags": [ "Sync flow settings" ], "summary": "Get preferences for text fields", "description": "Return preferences set for the text fields on sync flow.", "operationId": "get-config-text-sync-flow", "x-speakeasy-name-override": "get-config-text-sync-flow", "parameters": [ { "$ref": "#/components/parameters/locale" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalizationInfo" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "patch": { "tags": [ "Sync flow settings" ], "summary": "Update preferences for text fields", "description": "Set preferences for the text fields on sync flow.", "operationId": "update-config-text-sync-flow", "x-speakeasy-name-override": "update-config-text-sync-flow", "parameters": [ { "$ref": "#/components/parameters/locale" } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalizationInfo" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalizationInfo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/clients/{clientId}/config/ui/accounts/platform/{platformKey}": { "parameters": [ { "$ref": "#/components/parameters/clientId" }, { "$ref": "#/components/parameters/platformKey" } ], "get": { "tags": [ "Sync flow settings" ], "summary": "List visible accounts", "description": "Return accounts which are visible on sync flow.", "operationId": "get-visible-accounts", "x-speakeasy-name-override": "get-visible-accounts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibleAccounts" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/sync/commerce/config/ui/accounts/platform/{platformKey}": { "post": { "tags": [ "Sync flow settings" ], "summary": "Update visible accounts", "description": "Update which accounts are visible on sync flow.", "operationId": "update-visible-accounts-sync-flow", "x-speakeasy-name-override": "update-visible-accounts-sync-flow", "parameters": [ { "$ref": "#/components/parameters/platformKey" } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibleAccounts" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibleAccounts" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/sync/commerce/latest": { "post": { "tags": [ "Sync" ], "summary": "Initiate new sync", "description": "Run a Commerce sync from the last successful sync up to the date provided (optional), otherwise UtcNow is used.\\r\\nIf there was no previously successful sync, the start date in the config is used.", "operationId": "request-sync", "x-speakeasy-name-override": "request", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncToLatestArgs" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "x-speakeasy-usage-example": true, "schema": { "$ref": "#/components/schemas/SyncSummary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "parameters": [ { "$ref": "#/components/parameters/companyId" } ] }, "/meta/companies/{companyId}/sync/commerce/historic": { "post": { "tags": [ "Sync" ], "summary": "Initiate sync for specific range", "description": "Initiate a sync for the specified start date to the specified finish date in the request payload.", "operationId": "request-sync-for-date-range", "x-speakeasy-name-override": "request-for-date-range", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRange" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSummary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/meta/companies/{companyId}/sync/commerce/status": { "get": { "tags": [ "Sync" ], "summary": "Get sync status", "description": "Gets a list of sync statuses.", "operationId": "get-sync-status", "x-speakeasy-name-override": "get-status", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "parameters": [ { "$ref": "#/components/parameters/companyId" } ] }, "/companies/{companyId}/sync/commerce/syncs/lastSuccessful/status": { "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "get": { "description": "Gets the status of the last successful sync", "summary": "Last successful sync", "operationId": "get-last-successful-sync", "x-speakeasy-name-override": "get-last-successful-sync", "tags": [ "Sync" ], "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySyncStatus" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/sync/commerce/syncs/latest/status": { "get": { "description": "Gets the latest sync status", "summary": "Latest sync status", "operationId": "get-latest-sync", "x-speakeasy-name-override": "get-latest-sync", "tags": [ "Sync" ], "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySyncStatus" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "parameters": [ { "$ref": "#/components/parameters/companyId" } ] }, "/companies/{companyId}/sync/commerce/syncs/{syncId}/status": { "get": { "tags": [ "Sync" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/syncId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySyncStatus" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } }, "summary": "Get sync status", "description": "Get the sync status for a specified sync", "operationId": "get-sync-by-id" }, "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/syncId" } ] }, "/companies/{companyId}/sync/commerce/syncs/list/status": { "get": { "summary": "List sync statuses", "description": "Gets a list of sync statuses", "operationId": "list-syncs", "tags": [ "Sync" ], "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySyncStatus" } }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "parameters": [ { "$ref": "#/components/parameters/companyId" } ] } }, "webhooks": { "connection.deleted": { "post": { "description": "Triggered when a connection is deleted.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Sync Connection Deleted": { "post": { "deprecated": true, "requestBody": { "description": "A Sync for Commerce connection is deleted.\n\nThis event type has been deprecated. Subscribe to the `connection.deleted` event type instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncConnectionDeletedWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } } }, "components": { "schemas": { "Branding": { "title": "Branding", "type": "object", "properties": { "logo": { "$ref": "#/components/schemas/Branding/definitions/brandingLogo" }, "button": { "$ref": "#/components/schemas/Branding/definitions/brandingButton" }, "sourceId": { "type": "string", "format": "uuid", "example": "35b92968-9851-4095-ad60-395c95cbcba4", "description": "A source-specific ID used to distinguish between different sources originating from the same data connection. In general, a data connection is a single data source. However, for TrueLayer, `sourceId` is associated with a specific bank and has a many-to-one relationship with the `integrationId`." } }, "definitions": { "brandingLogo": { "description": "Logo branding references.", "type": "object", "properties": { "full": { "$ref": "#/components/schemas/Branding/definitions/brandingImage" }, "square": { "$ref": "#/components/schemas/Branding/definitions/brandingImage" } } }, "brandingButton": { "type": "object", "description": "Button branding references.", "properties": { "default": { "$ref": "#/components/schemas/Branding/definitions/brandingImage" }, "hover": { "$ref": "#/components/schemas/Branding/definitions/brandingImage" } } }, "brandingImage": { "title": "Branding Image", "type": "object", "properties": { "image": { "$ref": "#/components/schemas/Branding/definitions/imageReference" } }, "examples": [] }, "imageReference": { "type": "object", "title": "Image Reference", "description": "Image reference.", "properties": { "src": { "type": "string", "format": "uri", "description": "Source URL for image." }, "alt": { "type": "string", "description": "Alternative text when image is not available." } } } }, "examples": [ { "logo": { "full": { "image": { "src": "https://static.codat.io/public/officialLogos/Full/8A156A5A-39CB-4F9D-856E-76EF9B9A9607.png", "alt": "xero full icon" } }, "square": { "image": { "src": "https://static.codat.io/public/officialLogos/Square/8A156A5A-39CB-4F9D-856E-76EF9B2W3607.png", "alt": "xero square icon" } } }, "button": { "default": { "image": { "src": "https://static.codat.io/public/officialButtons/Full/8A156A5A-39CB-4F9D-856E-76EF9Q7A9607.png", "alt": "xero default button icon" } }, "hover": { "image": { "src": "https://static.codat.io/public/officialLogos/Full/8A156A5A-39CB-4F9D-856E-76EF9B9A9607.png", "alt": "xero hover button icon" } } }, "sourceId": "35b92968-9851-4095-ad60-395c95cbcba4" } ] }, "Companies": { "title": "Companies", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "Company": { "title": "Company", "description": "In Codat, a company represents a business sharing access to their data. Each company can have multiple [connections](https://docs.codat.io/sync-for-sync-for-commerce-api#/schemas/Connection) to different data sources such as one connection to [Xero](https://docs.codat.io/integrations/accounting/xero/accounting-xero) for accounting data, two connections to [Plaid](https://docs.codat.io/integrations/banking/plaid/banking-plaid) for two bank accounts and a connection to [Zettle](https://docs.codat.io/integrations/commerce/zettle/commerce-zettle) for POS data.\n\nTypically each company is one of your customers.\n\nWhen you create a company, you can specify a `name` and we will automatically generate a unique `id` for the company. You can also add a `description` to store any additional information about the company.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Company/definitions/companyDetails" }, { "type": "object", "properties": { "dataConnections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } } ], "definitions": { "companyDetails": { "title": "Company details", "type": "object", "properties": { "id": { "$ref": "#/components/parameters/companyId/schema" }, "name": { "type": "string", "description": "The name of the company", "example": "Codat Ltd." }, "description": { "$ref": "#/components/schemas/CreateCompany/properties/description", "nullable": true }, "redirect": { "type": "string", "format": "uri", "description": "The `redirect` [Link URL](https://docs.codat.io/auth-flow/authorize-hosted-link) enabling the customer to start their auth flow journey for the company.", "example": "https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739" }, "lastSync": { "$ref": "#/components/schemas/Connection/properties/created", "nullable": true }, "created": { "$ref": "#/components/schemas/Connection/properties/created" }, "createdByUserName": { "type": "string", "description": "Name of user that created the company in Codat.", "nullable": true }, "products": { "type": "array", "items": { "type": "string" }, "description": "An array of products that are currently enabled for the company." }, "tags": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^.{1,27}$" }, "additional properties": { "type": "string", "maxLength": 100 }, "description": "A collection of user-defined key-value pairs that store custom metadata against the company." } }, "required": [ "id", "name", "redirect" ] }, "companyReference": { "title": "Company reference", "type": "object", "properties": { "id": { "$ref": "#/components/parameters/companyId/schema" }, "name": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/name" }, "description": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/description" }, "links": { "type": "object", "description": "A collection of links for the company.", "properties": { "portal": { "type": "string", "format": "uri", "description": "Link to the company page in the portal." } } }, "tags": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/tags" } } } }, "examples": [ { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "string", "redirect": "https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739", "lastSync": "2022-01-01T12:00:00.000Z", "created": "2022-01-01T12:00:00.000Z", "createdByUserName": "string", "tags": { "region": "us", "uid": "f6b0c253-16c7-4da1-a0c5-9c871e9c9d6c" }, "dataConnections": [ { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } ] } ] }, "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.", "examples": [ "Complete", "PushError", "Started", "NotStarted", "Pushing" ], "nullable": true }, "errorMessage": { "type": "string", "description": "Error message of the sync.", "nullable": true }, "syncExceptionMessage": { "type": "string", "description": "Exception message of the sync.", "nullable": true }, "syncUtc": { "$ref": "#/components/schemas/Connection/properties/created", "description": "Datetime of the sync.", "nullable": true }, "dataPushed": { "type": "boolean", "description": "Boolean of whether the sync resulted in data being pushed." } } }, "Configuration": { "title": "Configuration", "type": "object", "properties": { "companyId": { "$ref": "#/components/parameters/companyId" }, "accountingSoftwareCompanyName": { "type": "string", "description": "The company name defined in the accounting software." }, "enable": { "type": "boolean", "description": "True if Sync for Commerce is enabled for the company." }, "configured": { "type": "boolean", "description": "True if Sync for Commerce has been configured for the company." }, "schedule": { "$ref": "#/components/schemas/Configuration/definitions/syncSchedule" }, "configuration": { "$ref": "#/components/schemas/Configuration/definitions/commerceConfiguration" } }, "definitions": { "syncSchedule": { "title": "Sync schedule", "type": "object", "properties": { "selectedFrequency": { "$ref": "#/components/schemas/Configuration/definitions/syncFrequency" }, "frequencyOptions": { "type": "array", "items": { "$ref": "#/components/schemas/Configuration/definitions/syncFrequency" } }, "startDate": { "$ref": "#/components/schemas/Connection/properties/created", "description": "The date time in UTC syncs should start from." }, "syncHour": { "type": "integer", "minValue": 0, "maxValue": 23, "description": "The hour you want to trigger a sync." }, "timeZone": { "type": "string", "description": "The timezone for the company.", "example": "Europe/London" } } }, "syncFrequency": { "type": "string", "enum": [ "Daily", "Monthly" ], "description": "The frequency in which you want data to be synced." }, "commerceConfiguration": { "title": "Commerce configuration", "type": "object", "properties": { "countryCode": { "type": "string", "description": "The country code outlining where the company is based." }, "mapSettings": { "$ref": "#/components/schemas/Configuration/definitions/configurationMapSettings" }, "sales": { "$ref": "#/components/schemas/Configuration/definitions/salesConfiguration" }, "payments": { "$ref": "#/components/schemas/Configuration/definitions/paymentsConfiguration" }, "newPayments": { "$ref": "#/components/schemas/Configuration/definitions/newPaymentsConfiguration" }, "fees": { "$ref": "#/components/schemas/Configuration/definitions/feesConfiguration" } } }, "configurationMapSettings": { "title": "Map settings", "type": "object", "properties": { "outputFormat": { "type": "string", "enum": [ "JournalEntry" ], "description": "The format commerce transactions are stored in the accounting software." } } }, "salesConfiguration": { "title": "Sales configuration", "type": "object", "properties": { "syncSales": { "type": "boolean", "description": "Boolean indicator for syncing sales." }, "accounts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Configuration/definitions/accountConfiguration" }, "nullable": true }, "invoiceStatus": { "$ref": "#/components/schemas/Configuration/definitions/invoiceStatus" }, "salesCustomer": { "$ref": "#/components/schemas/Configuration/definitions/salesCustomer" }, "taxRates": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Configuration/definitions/taxRateAmount" }, "nullable": true }, "newTaxRates": { "$ref": "#/components/schemas/Configuration/definitions/newTaxRates" }, "grouping": { "$ref": "#/components/schemas/Configuration/definitions/grouping" } } }, "paymentsConfiguration": { "title": "Payments configuration", "type": "object", "properties": { "syncPayments": { "type": "boolean", "description": "Boolean indicator for syncing sales." }, "accounts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Configuration/definitions/accountConfiguration" }, "nullable": true } }, "additionalProperties": false }, "newPaymentsConfiguration": { "title": "New payments configuration", "type": "object", "properties": { "syncPayments": { "type": "boolean", "description": "Boolean indicator for syncing payments." }, "accounts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Configuration/definitions/accountConfiguration" }, "nullable": true } }, "additionalProperties": false }, "feesConfiguration": { "title": "Fees configuration", "type": "object", "properties": { "feesSupplier": { "$ref": "#/components/schemas/Configuration/definitions/feesSupplier" }, "syncFees": { "type": "boolean", "description": "Boolean indicator to enable syncing fees." }, "accounts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Configuration/definitions/accountConfiguration" }, "nullable": true } }, "additionalProperties": false }, "accountConfiguration": { "title": "Account configuration", "type": "object", "description": "G/L account object for configuration.", "properties": { "labelText": { "type": "string", "nullable": true, "description": "Label text for sales configuration section." }, "descriptionText": { "type": "string", "nullable": true, "description": "Descriptive text for sales configuration section." }, "selectedAccountId": { "type": "string", "nullable": true, "description": "Selected account id from the list of available accounts." }, "required": { "type": "boolean", "description": "Required section to be configured for sync." }, "accountOptions": { "type": "array", "description": "Object containing account options.", "items": { "$ref": "#/components/schemas/Configuration/definitions/accountConfigurationOption" }, "nullable": true } }, "additionalProperties": false }, "accountConfigurationOption": { "title": "Account configuration option", "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for the account, unique for the company." }, "name": { "type": "string", "nullable": true, "description": "Name of the account." }, "nominalCode": { "type": "string", "nullable": true, "description": "Reference given to each nominal account for a business. It ensures money is allocated to the correct account. This code isn't a unique identifier in the Codat system." }, "classification": { "type": "string", "nullable": true, "description": "Classification of the type of G/L account.", "example": "Bank Nominal" } }, "additionalProperties": false }, "invoiceStatus": { "title": "Invoice status", "type": "object", "properties": { "selectedInvoiceStatus": { "type": "string", "nullable": true, "description": "Selected option for invoice status for invoice to be synced.", "example": "Submitted" }, "invoiceStatusOptions": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Options for invoice statuses." } }, "additionalProperties": false }, "salesCustomer": { "title": "Customer", "x-internal": true, "type": "object", "properties": { "selectedCustomerId": { "type": "string", "nullable": true, "description": "Selected customer id from the list of customer records on the accounting software." }, "customerOptions": { "type": "array", "description": "List of customer options from the list of customer records on the accounting software.", "items": { "$ref": "#/components/schemas/Configuration/definitions/configurationOption" }, "nullable": true } }, "additionalProperties": false }, "configurationOption": { "title": "Option", "type": "object", "properties": { "name": { "type": "string", "description": "Name value of the option.", "nullable": true }, "id": { "type": "string", "description": "Unique identifier for the option." } }, "additionalProperties": false }, "taxRateAmount": { "title": "Tax rate amount", "type": "object", "properties": { "selectedTaxRateId": { "type": "string", "description": "Selected tax rate id from the list of tax rates on the accounting software.", "nullable": true }, "taxRateOptions": { "type": "array", "description": "Array of tax rate options object.", "items": { "$ref": "#/components/schemas/Configuration/definitions/configurationOption" }, "nullable": true } }, "additionalProperties": false }, "newTaxRates": { "title": "New tax rates", "type": "object", "properties": { "accountingTaxRateOptions": { "type": "array", "description": "Array of accounting tax rate options.", "items": { "$ref": "#/components/schemas/Configuration/definitions/configurationOption" }, "nullable": true }, "commerceTaxRateOptions": { "type": "array", "description": "Array of tax component options.", "items": { "$ref": "#/components/schemas/Configuration/definitions/configurationOption" }, "nullable": true }, "taxRateMappings": { "type": "array", "description": "Array of tax component to rate mappings.", "items": { "$ref": "#/components/schemas/Configuration/definitions/taxRateMapping" }, "nullable": true }, "selectedDefaultZeroTaxRateId": { "type": "string", "description": "Default tax rate selected for sync.", "nullable": true }, "defaultZeroTaxRateOptions": { "type": "array", "description": "Default zero tax rate selected for sync.", "items": { "$ref": "#/components/schemas/Configuration/definitions/configurationOption" }, "nullable": true } }, "additionalProperties": false }, "taxRateMapping": { "title": "Tax rate mapping", "type": "object", "properties": { "selectedCommerceTaxRateIds": { "type": "array", "items": { "type": "string" }, "description": "Selected tax component id from the list of tax components on the commerce software.", "nullable": true }, "selectedAccountingTaxRateId": { "type": "string", "nullable": true, "description": "Selected tax rate id from the list of tax rates on the accounting software." } }, "additionalProperties": false }, "grouping": { "title": "Grouping", "type": "object", "properties": { "groupingPeriod": { "$ref": "#/components/schemas/Configuration/definitions/groupingPeriod" }, "groupingLevels": { "$ref": "#/components/schemas/Configuration/definitions/groupingLevels" } }, "additionalProperties": false }, "groupingLevels": { "title": "Grouping levels", "type": "object", "properties": { "invoiceLevel": { "$ref": "#/components/schemas/Configuration/definitions/invoiceLevelSelection" }, "invoiceLineLevel": { "$ref": "#/components/schemas/Configuration/definitions/invoiceLineLevelSelection" } }, "additionalProperties": false }, "groupingPeriod": { "title": "Grouping period", "type": "object", "properties": { "selectedGroupingPeriod": { "type": "string", "nullable": true, "description": "Grouping period i.e. Daily sales." }, "groupingPeriodOptions": { "type": "array", "description": "Array of grouping period options.", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "invoiceLevelSelection": { "title": "Invoice level selection", "type": "object", "properties": { "selectedGroupByOptions": { "type": "array", "description": "Selected array of grouping options.", "items": { "type": "string" }, "nullable": true }, "groupByOptions": { "type": "array", "description": "Options for grouping sales.", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "invoiceLineLevelSelection": { "title": "Invoice line level selection", "type": "object", "properties": { "selectedGroupByOptions": { "type": "array", "description": "Invoice line level selection.", "items": { "type": "string" }, "nullable": true }, "groupByOptions": { "type": "array", "description": "Options for grouping on invoice lines.", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "feesSupplier": { "title": "Supplier fees", "type": "object", "properties": { "selectedSupplierId": { "type": "string", "nullable": true, "description": "Selected supplier id from the list of supplier records on the accounting software." }, "supplierOptions": { "type": "array", "description": "List of supplier options from the list of supplier records on the accounting software.", "items": { "$ref": "#/components/schemas/Configuration/definitions/configurationOption" }, "nullable": true } }, "additionalProperties": false } } }, "Connection": { "title": "Connection", "description": "A connection represents a [company's](https://docs.codat.io/sync-for-sync-for-commerce-api#/schemas/Company) connection to a data source and allows you to synchronize data (pull and/or push) with that source.\n\nA company can have multiple data connections depending on the type of data source it is connecting to. For example, a single company can link to:\n\n- [Accounting data](https://docs.codat.io/accounting-api/overview) - 1 active connection.\n- [Banking data](https://docs.codat.io/banking-api/overview) - Multiple active connections.\n- [Commerce data](https://docs.codat.io/commerce-api/overview) - Multiple active connections.\nAny combination of accounting, banking, and commerce data connections is allowed.\n\nBefore you can use a data connection to pull or push data, the company must grant you access to their business data by [linking the connection](https://docs.codat.io/auth-flow/overview).", "type": "object", "properties": { "id": { "$ref": "#/components/parameters/connectionId/schema" }, "integrationId": { "type": "string", "format": "uuid", "example": "fd321cb6-7963-4506-b873-e99593a45e30", "description": "A Codat ID representing the integration." }, "integrationKey": { "type": "string", "description": "A unique four-character ID that identifies the platform of the company's data connection. This ensures continuity if the platform changes its name in the future." }, "sourceId": { "$ref": "#/components/schemas/Branding/properties/sourceId" }, "sourceType": { "$ref": "#/components/schemas/Integration/definitions/sourceType" }, "platformName": { "type": "string", "description": "Name of integration connected to company." }, "linkUrl": { "type": "string", "format": "uri", "description": "The link URL your customers can use to authorize access to their business application.", "example": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/2e2eb431-c1fa-4dc9-93fa-d29781c12bcd/start" }, "status": { "$ref": "#/components/schemas/Connection/definitions/dataConnectionStatus" }, "lastSync": { "$ref": "#/components/schemas/Connection/properties/created", "nullable": true }, "created": { "title": "Date time", "type": "string", "examples": [ "2022-10-23T00:00:00.000Z", "2022-10-23T00:00:00.000Z" ], "description": "In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example:\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", "nullable": true, "items": { "$ref": "#/components/schemas/Connection/definitions/dataConnectionError" } }, "connectionInfo": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } } }, "additionalProperties": false, "required": [ "id", "integrationId", "integrationKey", "sourceId", "platformName", "linkUrl", "status", "created", "sourceType" ], "definitions": { "dataConnectionStatus": { "title": "Data connection status", "description": "The current authorization status of the data connection.", "type": "string", "enum": [ "PendingAuth", "Linked", "Unlinked", "Deauthorized" ] }, "dataConnectionError": { "title": "Data connection error", "type": "object", "properties": { "statusCode": { "type": "string", "description": "The HTTP status code returned by the source platform when the error occurred." }, "statusText": { "type": "string", "description": "A non-numeric status code/text returned by the source platform when the error occurred." }, "errorMessage": { "type": "string", "description": "A message about a error returned by Codat." }, "erroredOnUtc": { "$ref": "#/components/schemas/Connection/properties/created" }, "status": { "title": "Error status", "description": "The current status of a transient error. Null statuses indicate that the error is not transient.", "type": "string", "nullable": true, "enum": [ "Active", "Resolved" ] }, "resolvedOnUtc": { "description": "The datetime in Utc that the error was resolved.", "nullable": true, "$ref": "#/components/schemas/Connection/properties/created" } } }, "dataConnectionSourceType": { "title": "Source Type", "description": "The type of platform of the connection.", "type": "string", "enum": [ "Accounting", "Banking", "BankFeed", "Commerce", "Expense", "Other", "Unknown" ], "example": "Accounting" } }, "example": { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } }, "Connections": { "title": "Connections", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "ConnectionWebhook": { "title": "Connection webhook", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "ba29118f-5406-4e59-b05c-ba307ca38d01", "description": "Unique identifier of the event." }, "eventType": { "type": "string", "description": "The type of event.", "examples": [ "connection.created", "connection.connected", "connection.disconnected", "connection.reconnected", "connection.deleted" ] }, "generatedDate": { "$ref": "#/components/schemas/Connection/properties/created", "description": "The date time in UTC the event was generated in Codat." }, "payload": { "$ref": "#/components/schemas/ConnectionWebhook/definitions/connectionWebhookPayload" } }, "definitions": { "connectionWebhookPayload": { "title": "Connection webhook payload", "type": "object", "properties": { "referenceCompany": { "$ref": "#/components/schemas/Company/definitions/companyReference" }, "connection": { "$ref": "#/components/schemas/Connection" } } } } }, "CreateCompany": { "title": "Create company request", "x-internal": true, "type": "object", "properties": { "name": { "type": "string", "description": "Name of company being connected.", "pattern": "^[A-Za-z0-9\\s\\-',&@.,?!\\s]+$", "minLength": 1, "example": "Bank of Dave" }, "description": { "type": "string", "example": "Requested early access to the new financing scheme.", "description": "Additional information about the company. This can be used to store foreign IDs, references, etc." }, "tags": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/tags" } }, "required": [ "name" ] }, "ErrorMessage": { "title": "Error message", "type": "object", "x-internal": true, "properties": { "statusCode": { "type": "integer", "description": "The HTTP status code returned by the error." }, "service": { "type": "string", "description": "Codat's service the returned the error." }, "error": { "type": "string", "description": "A brief description of the error." }, "correlationId": { "type": "string", "description": "Unique identifier used to propagate to all downstream services and determine the source of the error." }, "validation": { "$ref": "#/components/schemas/ErrorMessage/definitions/errorValidation" }, "canBeRetried": { "type": "string", "description": "`True` if the error occurred transiently and can be retried." }, "detailedErrorCode": { "type": "integer", "description": "Machine readable error code used to automate processes based on the code returned." } }, "definitions": { "errorValidation": { "title": "Validation error", "type": "object", "nullable": true, "description": "A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.", "properties": { "errors": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ErrorMessage/definitions/errorValidationItem" } }, "warnings": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ErrorMessage/definitions/errorValidationItem" } } } }, "errorValidationItem": { "title": "Validation error item", "type": "object", "properties": { "itemId": { "type": "string", "nullable": true, "description": "Unique identifier for a validation item." }, "message": { "type": "string", "nullable": true, "description": "A message outlining validation item's issue." }, "validatorName": { "type": "string", "nullable": true, "description": "Name of validator." } } } } }, "Integration": { "title": "Integration", "description": "An integration that Codat supports", "examples": [ { "key": "gbol", "logoUrl": "http://example.com", "name": "Xero", "enabled": true, "sourceId": "accounting", "sourceType": "8193a927-ab7a-45a3-9dc2-d357a4932dfe", "integrationId": "497a18ca-284e-40c0-985d-f72be35d468e", "isOfflineConnector": true, "isBeta": true, "dataProvidedBy": "string", "datatypeFeatures": [ { "datatype": "invoices", "supportedFeatures": [ { "featureType": "get", "featureState": "release" } ] } ] } ], "type": "object", "properties": { "key": { "$ref": "#/components/parameters/platformKey/schema" }, "logoUrl": { "type": "string", "format": "uri", "description": "Static url for integration's logo." }, "name": { "type": "string", "example": "Xero", "description": "Name of integration." }, "enabled": { "type": "boolean", "description": "Whether this integration is enabled for your customers to use." }, "sourceId": { "$ref": "#/components/schemas/Branding/properties/sourceId" }, "sourceType": { "$ref": "#/components/schemas/Integration/definitions/sourceType" }, "integrationId": { "$ref": "#/components/schemas/Connection/properties/integrationId" }, "isOfflineConnector": { "type": "boolean", "description": "`True` if the integration is to an application installed and run locally on an SMBs computer." }, "isBeta": { "type": "boolean", "description": "`True` if the integration is currently in beta release." }, "dataProvidedBy": { "type": "string", "description": "The name of the data provider." }, "datatypeFeatures": { "type": "array", "items": { "$ref": "#/components/schemas/Integration/definitions/dataTypeFeature" } } }, "required": [ "key", "logoUrl", "name", "enabled" ], "definitions": { "sourceType": { "title": "Source Type", "description": "The type of platform of the connection.", "type": "string", "enum": [ "Accounting", "Banking", "BankFeed", "Commerce", "Expense", "Other", "Unknown" ], "example": "Accounting" }, "dataTypeFeature": { "title": "Data type feature", "description": "Describes support for a given datatype and associated operations", "type": "object", "properties": { "dataType": { "title": "Data types", "x-internal": true, "type": "string", "description": "Available data types", "enum": [ "accountTransactions", "balanceSheet", "bankAccounts", "bankTransactions", "billCreditNotes", "billPayments", "bills", "cashFlowStatement", "chartOfAccounts", "company", "creditNotes", "customers", "directCosts", "directIncomes", "invoices", "itemReceipts", "items", "journalEntries", "journals", "paymentMethods", "payments", "profitAndLoss", "purchaseOrders", "salesOrders", "suppliers", "taxRates", "trackingCategories", "transfers", "banking-accountBalances", "banking-accounts", "banking-transactionCategories", "banking-transactions", "commerce-companyInfo", "commerce-customers", "commerce-disputes", "commerce-locations", "commerce-orders", "commerce-paymentMethods", "commerce-payments", "commerce-productCategories", "commerce-products", "commerce-taxComponents", "commerce-transactions" ], "example": "invoices" }, "supportedFeatures": { "type": "array", "items": { "$ref": "#/components/schemas/Integration/definitions/supportedFeature" } } }, "required": [ "datatype", "supportedFeatures" ], "examples": [ { "datatype": "invoices", "supportedFeatures": [ { "featureType": "Get", "featureState": "Release" } ] } ] }, "supportedFeature": { "type": "object", "x-internal": true, "properties": { "featureType": { "$ref": "#/components/schemas/Integration/definitions/featureType" }, "featureState": { "$ref": "#/components/schemas/Integration/definitions/featureState" } }, "required": [ "featureType", "featureState" ] }, "featureState": { "title": "Feature state", "type": "string", "example": "Release", "description": "The current release state of the feature.", "enum": [ "Release", "Alpha", "Beta", "Deprecated", "NotSupported", "NotImplemented" ] }, "featureType": { "type": "string", "x-internal": true, "description": "The type of feature.", "enum": [ "Get", "Post", "Categorization", "Delete", "Put", "GetAsPdf", "DownloadAttachment", "GetAttachment", "GetAttachments", "UploadAttachment" ], "example": "Get" } } }, "Integrations": { "title": "Integrations", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "Localization": { "title": "Localization", "x-internal": true, "type": "object", "properties": { "text": { "type": "string", "description": "Value of the property.", "nullable": true }, "required": { "type": "boolean", "description": "`True` if required." } } }, "LocalizationInfo": { "title": "Localization info", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Localization" } }, "PagingInfo": { "type": "object", "title": "Pagination information", "x-internal": true, "properties": { "pageNumber": { "type": "integer", "description": "Current page number." }, "pageSize": { "type": "integer", "description": "Number of items to return in results array.", "maximum": 2000 }, "totalResults": { "type": "integer", "description": "Total number of items." }, "_links": { "$ref": "#/components/schemas/PagingInfo/definitions/links" } }, "definitions": { "links": { "title": "Hal Links", "type": "object", "required": [ "self", "current" ], "properties": { "self": { "$ref": "#/components/schemas/PagingInfo/definitions/halRef" }, "current": { "$ref": "#/components/schemas/PagingInfo/definitions/halRef" }, "next": { "$ref": "#/components/schemas/PagingInfo/definitions/halRef" }, "previous": { "$ref": "#/components/schemas/PagingInfo/definitions/halRef" } }, "examples": [ { "self": { "href": "/companies" }, "current": { "href": "/companies?page=1&pageSize=10" } } ] }, "halRef": { "title": "Hypertext reference", "type": "object", "properties": { "href": { "type": "string", "format": "uri-reference", "description": "Uri hypertext reference." } } } }, "required": [ "pageNumber", "pageSize", "totalResults", "_links" ], "examples": [ { "pageNumber": 1, "pageSize": 10, "totalResults": 1, "_links": { "self": { "href": "/companies/{id}/data/{dataType}" }, "current": { "href": "/companies/{id}/data/{dataType}?page=1&pageSize=10" } } } ] }, "SyncConnectionDeletedWebhook": { "title": "Sync connection deleted webhook", "description": "A Sync for Commerce connection is deleted.", "x-internal": true, "type": "object", "properties": { "ClientId": { "$ref": "#/components/parameters/clientId/schema" }, "ClientName": { "type": "string", "description": "Name of your client in Codat." }, "CompanyId": { "$ref": "#/components/parameters/companyId/schema" }, "RuleId": { "type": "string", "format": "uuid", "description": "Unique identifier for the rule.", "deprecated": true }, "RuleType": { "type": "string", "x-stoplight": { "id": "34d52a089f08a" }, "description": "The type of rule." }, "AlertId": { "type": "string", "format": "uuid", "description": "Unique identifier of the webhook event." }, "Message": { "type": "string", "description": "A human-readable message about the webhook." } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Sync Connection Deleted", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "Sync connection for company 8a210b68-6988-11ed-a1eb-0242ac120002 deleted" }, { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Sync Connection Deleted", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "Sync connection for company Tesco (8a210b68-6988-11ed-a1eb-0242ac120002) deleted" } ] }, "SyncFlowUrl": { "title": "Sync flow url", "type": "object", "properties": { "url": { "type": "string", "description": "Sync flow URL.", "example": "https://sync-flow-integration.codat.io/57b6fad9-e3ca-447b-89db-e4ffa21e6ef3/aiwb/mqjo/start?otp=836415" } } }, "SyncRange": { "x-internal": true, "title": "Data range", "type": "object", "required": [ "dateRange" ], "properties": { "dateRange": { "type": "object", "properties": { "start": { "$ref": "#/components/schemas/Connection/properties/created", "description": "Start date of the Sync." }, "finish": { "$ref": "#/components/schemas/Connection/properties/created", "description": "Finish date of the Sync." } }, "required": [ "start", "finish" ] } } }, "SyncStatus": { "title": "Sync status", "description": "The status of syncing for a company and its connections.", "type": "object", "x-examples": { "4200": { "companyId": "782575ae-c4f8-4a0b-8041-4ffa193aaab7", "commerceSyncId": "78ab9424-bb29-47d2-b808-4c6e651efd6d", "syncId": "afe076de-4d1b-44d8-8b4a-717463af00c5", "syncStatusCode": "4200,", "syncStatus": "MapCoreError", "errorMessage": "Cannot match the tax id '23vwUg7OhGIZvEUHdee7fw' to a mapped account on the accounting software for journal entry.", "syncExceptionMessage": "Cannot match the tax id '23vwUg7OhGIZvEUHdee7fw' to a mapped account on the accounting software for journal entry.", "syncUtc": "2023-04-12T10:52:54.5359678Z", "dataPushed": false, "dataConnections": [ { "id": "9bd6cb3b-06b3-4944-91e6-7dffbf5846a2", "integrationId": "3485371f-930d-4614-997a-5dfa2cec546c", "integrationKey": "lqai", "sourceId": "c4f9fa2d-cb83-4a3f-9b36-45b4af190e81", "platformName": "Partner Commerce", "linkUrl": "https://link-api.codat.io/companies/0bfd6552-7712-45bb-8c67-c4eabd7ec78e/connections/248f3e4e-8b71-44a1-b091-69ac25b86e6c/start", "status": "Linked", "lastSync": "2023-06-14T11:58:52.2695708Z", "created": "2023-06-14T11:39:00Z", "sourceType": "Commerce", "dataConnectionErrors": [] }, { "id": "ff8f694d-1a8f-4b00-99d7-26173aff34eb", "integrationId": "adeb7fe9-4c64-4848-9e0d-175317876b6f", "integrationKey": "qhyg", "sourceId": "afe268b1-289e-4496-b890-3d65e9ce1acb", "platformName": "QuickBooks Online", "linkUrl": "https://link-api.codat.io/companies/0bfd6552-7712-45bb-8c67-c4eabd7ec78e/connections/1486b3db-f752-467a-9d56-66dd57cc754d/start", "status": "Linked", "lastSync": "2023-08-10T17:50:14.0900922Z", "created": "2023-06-14T11:39:00Z", "sourceType": "Accounting", "dataConnectionErrors": [] } ] } }, "properties": { "companyId": [ { "$ref": "#/components/parameters/companyId" } ], "commerceSyncId": { "type": "string", "format": "guid", "description": "Unique identifier for the sync in Codat.", "example": "8d0a044e-b683-4fc9-bd0d-bfb2ca5731b7" }, "syncId": { "type": "string", "format": "uuid", "example": "730dcf2e-3afc-4d83-bb90-9f4b95dddf68", "description": "Unique identifier for the sync in Codat." }, "syncStatusCode": { "type": "integer", "format": "int32", "description": "Numerical status code sync of the company data.", "example": 4000 }, "syncStatus": { "type": "string", "nullable": true, "description": "Status of the sync of the company data. This is linked to status code.", "example": "ValidateError, Pending" }, "errorMessage": { "type": "string", "nullable": true, "description": "Friendly error message for the sync operation.", "example": "Customer 3b9bf2ed-a618-4af2-80f2-f2b57fddc748 is not in an Active state. (Archived)" }, "syncExceptionMessage": { "type": "string", "nullable": true, "description": "Exception message for the sync operation.", "example": "Customer 3b9bf2ed-a618-4af2-80f2-f2b57fddc748 is not in an Active state. (Archived)" }, "syncUtc": { "$ref": "#/components/schemas/Connection/properties/created", "description": "UTC DateTime for the Sync.", "nullable": true }, "dataPushed": { "type": "boolean", "description": "Boolean indicator for data being pushed during a sync operation.", "example": true }, "dataConnections": { "type": "array", "description": "Array of containing objects data connection information for the company.", "items": { "$ref": "#/components/schemas/Connection" }, "nullable": true } }, "additionalProperties": false }, "SyncSummary": { "title": "Sync summary", "type": "object", "properties": { "syncDateRangeUtc": { "type": "object", "properties": { "start": { "$ref": "#/components/schemas/Connection/properties/created", "description": "Start date of the Sync." }, "finish": { "$ref": "#/components/schemas/Connection/properties/created", "description": "Finish date of the Sync." } }, "additionalProperties": false }, "companyId": { "type": "string", "format": "guid", "description": "Unique identifier for your SMB in Codat.", "example": "f4637ec9-9fc0-4a02-8df0-c90d6dc86208" }, "commerceSyncId": { "type": "string", "format": "guid", "description": "Unique identifier for the sync in Codat.", "example": "8d0a044e-b683-4fc9-bd0d-bfb2ca5731b7" }, "syncStatusCode": { "type": "integer", "format": "int32", "description": "Numerical status code sync of the company data.", "example": 4000 }, "syncStatus": { "type": "string", "nullable": true, "description": "Status of the sync of the company data. This is linked to status code.", "example": "ValidateError, Pending" }, "errorMessage": { "type": "string", "nullable": true, "description": "Friendly error message for the sync operation.", "example": "Customer 3b9bf2ed-a618-4af2-80f2-f2b57fddc748 is not in an Active state. (Archived)" }, "syncExceptionMessage": { "type": "string", "nullable": true, "description": "Exception message for the sync operation.", "example": "Customer 3b9bf2ed-a618-4af2-80f2-f2b57fddc748 is not in an Active state. (Archived)" }, "syncUtc": { "$ref": "#/components/schemas/Connection/properties/created", "description": "UTC DateTime for the Sync.", "nullable": true }, "dataConnections": { "type": "array", "description": "Array of containing objects data connection information for the company.", "items": { "$ref": "#/components/schemas/Connection" }, "nullable": true }, "dataPushed": { "type": "boolean", "description": "Boolean indicator for data being pushed during a sync operation.", "example": true } }, "additionalProperties": false }, "SyncToLatestArgs": { "title": "Sync To Latest Args", "x-internal": true, "type": "object", "properties": { "syncTo": { "$ref": "#/components/schemas/Connection/properties/created", "description": "The DateTime, upto which Sync will run up to starting from the previous successful sync", "nullable": true } } }, "UpdateConnection": { "title": "Update connection", "x-internal": true, "type": "object", "properties": { "status": { "$ref": "#/components/schemas/Connection/definitions/dataConnectionStatus", "description": "The current authorization status of the data connection.", "nullable": true } }, "additionalProperties": false }, "VisibleAccounts": { "title": "Visible accounts", "type": "object", "properties": { "visibleAccounts": { "description": "Visible accounts on sync flow.", "type": "array", "items": { "type": "string" }, "nullable": true } } } }, "responses": { "BadRequest": { "description": "The request made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Malformed query": { "value": { "statusCode": 400, "service": "PublicApi", "error": "Error processing request - not valid.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Malformed-Query": { "description": "Your `query` parameter was not correctly formed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Malformed query": { "value": { "statusCode": 400, "service": "ClientsApi", "error": "Error parsing query - Malformed query.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } }, "Unresolved property": { "value": { "statusCode": 400, "service": "PullApi", "error": "Error parsing query - Could not resolve property isCompleted on Dataset", "correlationId": "98457fb9956b7f9b4b2fd4f6e23bb5c8", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Unauthorized": { "description": "Your API request was not properly authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Unauthorized": { "value": { "statusCode": 401, "service": "PublicApi", "error": "Unauthorized", "correlationId": "7eb40d6b415d7bcd99ce658268284056", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Payment-Required": { "description": "An account limit has been exceeded. The type of limit is described in the error property:\n\n- You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request.\n- The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan.\n- Your Free account is older than 365 days and has expired. Contact support@codat.io.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 429, "service": "PublicApi", "error": "You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Forbidden": { "description": "You are using an outdated API key or a key not associated with that resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 403, "service": "PublicApi", "error": "You are using an outdated API key or a key not associated with that resource.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Not-Found": { "description": "One or more of the resources you referenced could not be found.\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 } } } } } }, "Internal-Server-Error": { "description": "There is a problem with our server. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 500, "service": "PublicApi", "error": "There is a problem with our server. Please try again later.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Service-Unavailable": { "description": "The Codat API is temporarily offline for maintenance. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 500, "service": "PublicApi", "error": "The Codat API is temporarily offline for maintenance. Please try again later.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } } }, "parameters": { "clientId": { "name": "clientId", "in": "path", "required": true, "schema": { "title": "Client ID", "type": "string", "format": "uuid", "description": "Unique identifier for your client in Codat." }, "description": "Unique identifier for your client in Codat." }, "companyId": { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "8a210b68-6988-11ed-a1eb-0242ac120002", "description": "Unique identifier for your SMB in Codat." }, "description": "Unique identifier for a company." }, "connectionId": { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "description": "Unique identifier for a company's data connection." }, "description": "Unique identifier for a connection." }, "page": { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int32", "minimum": 1, "example": 1, "default": 1 }, "description": "Page number. [Read more](https://docs.codat.io/using-the-api/paging)." }, "pageSize": { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "example": 100, "minimum": 1, "maximum": 5000 }, "description": "Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging)." }, "query": { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "example": "id=e3334455-1aed-4e71-ab43-6bccf12092ee", "description": "Codat query string. [Read more](https://docs.codat.io/using-the-api/querying)." }, "orderBy": { "name": "orderBy", "in": "query", "required": false, "schema": { "type": "string", "example": "-modifiedDate" }, "description": "Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results)." }, "syncId": { "name": "syncId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "6fb40d5e-b13e-11ed-afa1-0242ac120002" }, "description": "Unique identifier for a sync." }, "platformKey": { "name": "platformKey", "in": "path", "required": true, "schema": { "type": "string", "minLength": 4, "maxLength": 4, "pattern": "[a-z]{4}", "example": "gbol", "description": "A unique 4-letter key to represent a platform in each integration. View [accounting](https://docs.codat.io/integrations/accounting/overview#platform-keys), [banking](https://docs.codat.io/integrations/banking/overview#platform-keys), and [commerce](https://docs.codat.io/integrations/commerce/overview#platform-keys) platform keys." }, "description": "A unique 4-letter key to represent a platform in each integration." }, "locale": { "name": "locale", "in": "query", "required": true, "example": "en-us", "schema": { "type": "string", "enum": [ "en-us", "fr-fr" ] }, "description": "Localization identifier for English (US) or French." } }, "securitySchemes": { "auth_header": { "name": "Authorization", "description": "The word \"Basic\" followed by a space and your API key. [API keys](https://docs.codat.io/sync-for-sync-for-commerce-api#/schemas/apiKeys) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/codat-api#/api-keys/api-keys-list), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.", "type": "apiKey", "in": "header", "x-speakeasy-example": "Basic BASE_64_ENCODED(API_KEY)" } } } }