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 is an API and a set of supporting tools built to enable e-commerce and point of sale platforms to provide high-quality integrations with numerous accounting platform through standardized API, seamlessly transforming business sale's data into accounting artefacts. [Read More...](https://docs.codat.io/commerce/overview) 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: ^download-.*?-attachment methodNameOverride: download-attachment - operationId: ^upload-.*?-attachment methodNameOverride: upload-attachment x-codat-docs-path: sync-for-commerce-api tags: - name: Connections description: Create new and manage existing Sync for Commerce companies using the Sync flow UI. - name: Sync flow preferences description: Configure preferences for any given Sync for Commerce company using sync flow. - name: Sync description: Initiate and monitor the sync of company data into accounting software. - name: Integrations description: View useful information about codat's integrations. - name: Advanced controls description: Advanced company management and sync preferences. paths: '/config/sync/commerce/{commerceKey}/{accountingKey}/start': get: tags: - Connections summary: Retrieve sync flow url description: 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' parameters: - schema: type: string name: commerceKey in: path required: true description: Unique identifier for commerce platform. - 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' 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' '/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': 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 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' 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-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: type: string 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' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '/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' 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' 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' 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' /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' '/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: - name: platformKey in: path description: PlatformKey required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Branding' 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 preferences 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 responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/LocalizationInfo' patch: tags: - Sync flow preferences 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 requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/LocalizationInfo' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/LocalizationInfo' '/clients/{clientId}/config/ui/accounts/platform/{platformKey}': parameters: - name: clientId in: path required: true schema: type: string format: uuid - name: platformKey in: path required: true schema: type: string format: uuid get: tags: - Sync flow preferences 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' '/sync/commerce/config/ui/accounts/platform/{platformKey}': post: tags: - Sync flow preferences 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: - name: platformKey in: path required: true schema: type: string format: uuid requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/VisibleAccounts' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/VisibleAccounts' '/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' 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' '/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 parameters: - $ref: '#/components/parameters/companyId' '/companies/{companyId}/sync/commerce/syncs/lastSuccessful/status': get: 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' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' description: Gets the status of the last successful sync summary: Last successful sync operationId: get-last-successful-sync x-speakeasy-name-override: get-last-successful-sync parameters: - $ref: '#/components/parameters/companyId' '/companies/{companyId}/sync/commerce/syncs/latest/status': get: 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' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' description: Gets the latest sync status summary: Latest sync status operationId: get-latest-sync x-speakeasy-name-override: get-latest-sync parameters: - $ref: '#/components/parameters/companyId' '/companies/{companyId}/sync/expenses/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' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' summary: Get Sync status description: Get the sync status for a specified sync operationId: get-sync-by-id parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/syncId' '/companies/{companyId}/sync/commerce/syncs/list/status': get: 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' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' summary: List sync statuses description: Gets a list of sync statuses operationId: list-syncs parameters: - $ref: '#/components/parameters/companyId' components: schemas: SyncToLatestArgs: title: Sync To Latest Args x-internal: true type: object properties: syncTo: $ref: '#/components/schemas/Company/properties/created' description: 'The DateTime, upto which Sync will run up to starting from the previous successful sync' nullable: true SyncSummary: type: object properties: syncDateRangeUtc: $ref: '#/components/schemas/DateRange' 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/Company/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 DateRange: x-internal: true title: Data range type: object properties: start: $ref: '#/components/schemas/Company/properties/created' description: Start date of the Sync. finish: $ref: '#/components/schemas/Company/properties/created' description: Finish date of the Sync. additionalProperties: false SyncRange: x-internal: true title: Data range type: object required: - dateRange properties: dateRange: type: object properties: start: $ref: '#/components/schemas/Company/properties/created' description: Start date of the Sync. finish: $ref: '#/components/schemas/Company/properties/created' description: Finish date of the Sync. required: - start - finish CreateCompany: x-internal: true required: - name type: object properties: name: type: string format: string description: Name of the company in Codat with a partner-commerce data connection. example: Bob's Burgers additionalProperties: false Connection: title: Connection description: "\uFEFFA connection represents a [company's](https://docs.codat.io/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: title: Source Type x-internal: true description: The type of platform of the connection. type: string enum: - Accounting - Banking - Commerce - Other - Unknown example: Accounting platformName: type: string linkUrl: type: string format: uri example: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/2e2eb431-c1fa-4dc9-93fa-d29781c12bcd/start' status: $ref: '#/components/schemas/Connection/definitions/dataConnectionStatus' lastSync: $ref: '#/components/schemas/Company/properties/created' created: $ref: '#/components/schemas/Company/properties/created' dataConnectionErrors: type: array items: $ref: '#/components/schemas/Connection/definitions/dataConnectionError' connectionInfo: type: object additionalProperties: type: string additionalProperties: false required: - id - integrationId - integrationKey - sourceId - platformName - linkUrl - status - created - sourceType definitions: dataConnectionStatus: title: Data connection status description: The current authorization status of the data connection. type: string enum: - PendingAuth - Linked - Unlinked - Deauthorized dataConnectionError: title: Data connection error type: object properties: statusCode: type: string statusText: type: string errorMessage: type: string erroredOnUtc: $ref: '#/components/schemas/Company/properties/created' dataConnectionSourceType: title: Source Type description: The type of platform of the connection. type: string enum: - Accounting - Banking - Commerce - Other - Unknown example: Accounting example: id: ee2eb431-c0fa-4dc9-93fa-d29781c12bcd integrationId: bf083d72-62c7-493e-aec9-81b4dbba7e2c integrationKey: dfxm sourceId: bdd831ce-eebd-4896-89a7-20e5ee8989ee platformName: Basiq linkUrl: 'https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start' status: Linked lastSync: '2022-10-27T10:22:43.6464237Z' created: '2022-10-27T09:53:29Z' sourceType: Banking Connections: x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/Connection' - $ref: '#/components/schemas/PagingInfo' Companies: x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/Company' - $ref: '#/components/schemas/PagingInfo' PagingInfo: type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _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/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' halRef: title: Hypertext reference type: object properties: href: type: string format: uri-reference required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' Links: type: object x-internal: true required: - self - current properties: self: $ref: '#/components/schemas/HalRef' current: $ref: '#/components/schemas/HalRef' next: $ref: '#/components/schemas/HalRef' previous: $ref: '#/components/schemas/HalRef' examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' HalRef: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference 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-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 properties: id: $ref: '#/components/parameters/companyId/schema' name: type: string description: The name of the company example: Codat Ltd. 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.' platform: type: string deprecated: true example: Xero 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/Company/properties/created' created: title: Date time type: string examples: - 2022-10-23T00:00:00.000Z - 2022-10-23T00:00:00.000Z description: |- In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example: ``` 2020-10-08T22:40:50Z 2021-01-01T00:00:00 ``` When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information: - Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z` - Unqualified local time: `2021-11-15T01:00:00` - UTC time offsets: `2021-11-15T01:00:00-05:00` > Time zones > > Not all dates from Codat will contain information about time zones. > Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced. createdByUserName: type: string dataConnections: type: array items: $ref: '#/components/schemas/Connection' required: - id - name - redirect examples: - id: 0498e921-9b53-4396-a412-4f2f5983b0a2 name: string platform: 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 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 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 Integrations: x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/Integration' - $ref: '#/components/schemas/PagingInfo' 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: 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/accounting-platform-keys), [banking](https://docs.codat.io/integrations/banking/banking-platform-keys), and [commerce](https://docs.codat.io/integrations/commerce/commerce-platform-keys) platform keys. ' logoUrl: type: string format: uri name: type: string example: Xero 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/Connection/properties/sourceType' integrationId: $ref: '#/components/schemas/Connection/properties/integrationId' isOfflineConnector: type: boolean isBeta: type: boolean dataProvidedBy: type: string datatypeFeatures: type: array items: $ref: '#/components/schemas/Integration/definitions/dataTypeFeature' required: - key - logoUrl - name - enabled definitions: dataTypeFeature: title: Data type feature description: Describes support for a given datatype and associated operations type: object properties: dataType: 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 - 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 enum: - Release - Alpha - Beta - Deprecated - NotSupported - NotImplemented featureType: type: string x-internal: true enum: - Get - Post - Categorization - Delete - Put - GetAsPdf - DownloadAttachment - GetAttachment - GetAttachments - UploadAttachment example: Get UpdateConnection: x-internal: true type: object properties: status: type: string description: The current authorization status of the data connection. example: Linked nullable: true additionalProperties: false AccountOption: x-internal: true title: Account option type: object properties: name: type: string nullable: true description: Name of the account. id: type: string description: 'Identifier for the account, unique for the company.' 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 ConfigAccount: x-internal: true 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: Descriprtive 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/AccountOption' nullable: true additionalProperties: false Configuration: type: object properties: sales: $ref: '#/components/schemas/Sales' payments: $ref: '#/components/schemas/Payments' newPayments: $ref: '#/components/schemas/NewPayments' fees: $ref: '#/components/schemas/Fees' additionalProperties: false Fees: x-internal: true type: object properties: feesSupplier: $ref: '#/components/schemas/FeesSupplier' syncFees: type: boolean description: Boolean indicator to enable syncing fees. accounts: type: object additionalProperties: $ref: '#/components/schemas/ConfigAccount' nullable: true additionalProperties: false FeesSupplier: x-internal: true 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/Option' nullable: true additionalProperties: false Grouping: x-internal: true type: object properties: groupingPeriod: $ref: '#/components/schemas/GroupingPeriod' groupingLevels: $ref: '#/components/schemas/GroupingLevels' additionalProperties: false GroupingLevels: x-internal: true title: Grouping levels type: object properties: invoiceLevel: $ref: '#/components/schemas/InvoiceLevelSelection' invoiceLineLevel: $ref: '#/components/schemas/InvoiceLineLevelSelection' additionalProperties: false GroupingPeriod: x-internal: true 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: x-internal: true 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: x-internal: true 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 InvoiceStatus: x-internal: true 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 NewPayments: x-internal: true title: New payments type: object properties: syncPayments: type: boolean description: Boolean indicator for syncing payments. accounts: type: object additionalProperties: $ref: '#/components/schemas/ConfigAccount' nullable: true additionalProperties: false NewTaxRates: x-internal: true title: New tax rates type: object properties: accountingTaxRateOptions: type: array description: Array of accounting tax rate options. items: $ref: '#/components/schemas/Option' nullable: true commerceTaxRateOptions: type: array description: Array of tax component options. items: $ref: '#/components/schemas/Option' nullable: true taxRateMappings: type: array description: Array of tax component to rate mapppings. items: $ref: '#/components/schemas/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/Option' nullable: true additionalProperties: false Option: x-internal: true 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 Payments: x-internal: true type: object properties: syncPayments: type: boolean description: Boolean indicator for syncing sales. accounts: type: object additionalProperties: $ref: '#/components/schemas/ConfigAccount' nullable: true additionalProperties: false Sales: x-internal: true type: object properties: syncSales: type: boolean description: Boolean indicator for syncing sales. accounts: type: object additionalProperties: $ref: '#/components/schemas/ConfigAccount' nullable: true invoiceStatus: $ref: '#/components/schemas/InvoiceStatus' salesCustomer: $ref: '#/components/schemas/Customer' taxRates: type: object additionalProperties: $ref: '#/components/schemas/TaxRateAmount' nullable: true newTaxRates: $ref: '#/components/schemas/NewTaxRates' grouping: $ref: '#/components/schemas/Grouping' additionalProperties: false 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/Option' nullable: true additionalProperties: false TaxRateAmount: x-internal: true 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/Option' nullable: true additionalProperties: false TaxRateMapping: x-internal: true 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 Localization: x-internal: true type: object properties: text: type: string description: Value of the property. nullable: true required: type: boolean LocalizationInfo: title: Localization info. type: object additionalProperties: $ref: '#/components/schemas/Localization' VisibleAccounts: title: Visible accounts type: object properties: visibleAccounts: description: Visible accounts on sync flow. type: array items: type: string nullable: true 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' ErrorMessage: type: object x-internal: true properties: statusCode: type: integer service: type: string error: type: string correlationId: type: string canBeRetried: type: string detailedErrorCode: type: integer CompanySyncStatus: title: Company sync status type: object additionalProperties: false x-examples: Success Data Pushed: companyId: 20803807-4e9a-4cb7-b67b-9f889a3916e1 syncId: aa4c9dfd-e945-4424-9628-9e724f14c267 syncStatusCode: 2000 syncStatus: Complete errorMessage: '' syncExceptionMessage: '' syncUtc: '2023-01-24T14:15:22Z' dataPushed: true Success No Data Pushed: companyId: 20803807-4e9a-4cb7-b67b-9f889a3916e1 syncId: aa4c9dfd-e945-4424-9628-9e724f14c267 syncStatusCode: 2040 syncStatus: Complete errorMessage: '' syncExceptionMessage: '' syncUtc: '2023-01-24T14:15:22Z' dataPushed: false properties: companyId: type: string description: Unique identifier for your SMB in Codat. example: d4d73051-ed31-42b6-99f6-d288cd940992 nullable: true syncId: type: string description: Unique identifier of the sync. example: a6a22aff-a43a-411d-a910-2dae73217cce nullable: true syncStatusCode: type: integer format: int32 description: Status code of the sync. example: 2000 syncStatus: type: string description: Text status of the sync. example: Completed nullable: true errorMessage: type: string description: Error message of the sync. nullable: true syncExceptionMessage: type: string description: Exception message of the sync. nullable: true syncUtc: $ref: '#/components/schemas/Company/properties/created' description: Datetime of the sync. nullable: true dataPushed: type: boolean description: Boolean of whether the sync resulted in data being pushed. responses: Unauthorized: description: Your API request was not properly authorized. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Unauthorized: value: statusCode: 401 service: PublicApi error: Unauthorized correlationId: 7eb40d6b415d7bcd99ce658268284056 canBeRetried: Unknown detailedErrorCode: 0 Not-Found: description: |- One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Data connection not found: value: statusCode: 404 service: PublicApi error: Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found correlationId: 8fa2b5f4794970a4ee73758f612e8df0 canBeRetried: Unknown detailedErrorCode: 0 Company not found: value: statusCode: 404 service: ClientsApi error: No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e correlationId: 0a40c2f31fc8f992fb88b0853e4166f3 canBeRetried: Unknown detailedErrorCode: 0 No data available: value: statusCode: 404 service: PublicApi error: No data available for accounts for ID e5889b459f544926ac5b8e6756df2s correlationId: 0a40c2f31fc8f992fb88b0853e4166f3 canBeRetried: Unknown detailedErrorCode: 0 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 parameters: 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. 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. 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: '-modifiedDate' 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).' x-stoplight: id: 4je9lwo02netu syncId: name: syncId in: path required: true schema: type: string format: uuid example: 6fb40d5e-b13e-11ed-afa1-0242ac120002 description: Unique identifier for a sync. securitySchemes: auth_header: name: Authorization description: 'The word "Basic" followed by a space and your API key. [API keys](https://docs.codat.io/accounting-api#/schemas/apiKeys) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/codat-api#/api-keys/api-keys-list), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.' type: apiKey in: header x-speakeasy-example: Basic BASE_64_ENCODED(API_KEY)