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. Sync 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. [Explore product](https://docs.codat.io/commerce/overview) | [See our OpenAPI spec](https://github.com/codatio/oas) Not 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#/). --- ## Endpoints | Endpoints | Description | | :- |:- | | Connections | Create new and manage existing data connections for a company. | | Sync | Initiate data syncs and monitor their status. | | Sync flow settings | Control text and visibility settings for the Sync Flow. | | Integrations | Get a list of integrations supported by Sync for Commerce and their logos. | | Advanced controls | View and manage mapping configured for a company's commerce sync. | 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: "\uFEFFList the connections for a company." operationId: list-connections tags: - Connections parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/orderBy' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Connections' examples: Connections: value: results: - id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c integrationKey: dfxm sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee platformName: Basiq linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start' status: Linked lastSync: '2022-10-27T10:22:43.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking pageNumber: 0 pageSize: 0 totalResults: 0 _links: self: href: string current: href: string next: href: string previous: href: string '400': $ref: '#/components/responses/Malformed-Query' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' post: summary: Create connection description: "\uFEFFCreates a connection for the company by providing a valid `platformKey`. \n\nUse the [List Integrations](https://docs.codat.io/sync-for-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. This 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: "\uFEFFIn 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: "\uFEFFA 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: ``` 2020-10-08T22:40:50Z 2021-01-01T00:00:00 ``` When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information: - Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z` - Unqualified local time: `2021-11-15T01:00:00` - UTC time offsets: `2021-11-15T01:00:00-05:00` > Time zones > > Not all dates from Codat will contain information about time zones. > Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced. dataConnectionErrors: type: array nullable: true items: $ref: '#/components/schemas/Connection/definitions/dataConnectionError' connectionInfo: type: object nullable: true additionalProperties: type: string additionalProperties: false required: - id - integrationId - integrationKey - sourceId - platformName - linkUrl - status - created - sourceType definitions: dataConnectionStatus: title: Data connection status description: The current authorization status of the data connection. type: string enum: - PendingAuth - Linked - Unlinked - Deauthorized dataConnectionError: title: Data connection error type: object properties: statusCode: type: string description: The HTTP status code returned by the source platform when the error occurred. statusText: type: string description: A non-numeric status code/text returned by the source platform when the error occurred. errorMessage: type: string description: A message about a error returned by Codat. erroredOnUtc: $ref: '#/components/schemas/Connection/properties/created' status: title: Error status description: The current status of a transient error. Null statuses indicate that the error is not transient. type: string nullable: true enum: - Active - Resolved resolvedOnUtc: description: The datetime in Utc that the error was resolved. nullable: true $ref: '#/components/schemas/Connection/properties/created' dataConnectionSourceType: title: Source Type description: The type of platform of the connection. type: string enum: - Accounting - Banking - BankFeed - Commerce - Expense - Other - Unknown example: Accounting example: id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c integrationKey: dfxm sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee platformName: Basiq linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start' status: Linked lastSync: '2022-10-27T10:22:43.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking Connections: title: Connections x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/Connection' - $ref: '#/components/schemas/PagingInfo' 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: - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 429 service: PublicApi error: You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Forbidden: description: You are using an outdated API key or a key not associated with that resource. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 403 service: PublicApi error: You are using an outdated API key or a key not associated with that resource. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Not-Found: description: |- One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Data connection not found: value: statusCode: 404 service: PublicApi error: Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found correlationId: 8fa2b5f4794970a4ee73758f612e8df0 canBeRetried: Unknown detailedErrorCode: 0 Company not found: value: statusCode: 404 service: ClientsApi error: No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e correlationId: 0a40c2f31fc8f992fb88b0853e4166f3 canBeRetried: Unknown detailedErrorCode: 0 No data available: value: statusCode: 404 service: PublicApi error: No data available for accounts for ID e5889b459f544926ac5b8e6756df2s correlationId: 0a40c2f31fc8f992fb88b0853e4166f3 canBeRetried: Unknown detailedErrorCode: 0 Conflict: description: The data type's dataset has not been requested or is still syncing. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Conflict: value: statusCode: 409 service: PublicApi error: The data set has not been requested. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 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)