{ "openapi": "3.1.0", "x-stoplight": { "id": "466k6ayziv9at" }, "servers": [ { "description": "Production", "url": "https://api.codat.io" } ], "info": { "title": "Platform API", "version": "3.0.0", "summary": "Platform API", "description": "An API for the common components of all of Codat's products.\n\nThese end points cover creating and managing your companies, data connections, and integrations.\n\n[Read about the building blocks of Codat...](https://docs.codat.io/core-concepts/companies) | [See our OpenAPI spec](https://github.com/codatio/oas) \n\n---\n\n## Endpoints\n\n| Endpoints | Description |\n| :- |:- |\n| Companies | Create and manage your SMB users' companies. |\n| Connections | Create new and manage existing data connections for a company. |\n| Connection management | Configure connection management UI and retrieve access tokens for authentication. |\n| Webhooks | Create and manage webhooks that listen to Codat's events. |\n| Integrations | Get a list of integrations supported by Codat and their logos. |\n| Refresh data | Initiate data refreshes, view pull status and history. |\n| Settings | Manage company profile configuration, sync settings, and API keys. |\n| Push data | Initiate and monitor Create, Update, and Delete operations. |\n| Supplemental data | Configure and pull additional data you can include in Codat's standard data types. |\n| Custom data type | Configure and pull additional data types that are not included in Codat's standardized data model. |\n", "contact": { "name": "Codat", "email": "support@codat.io" }, "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": "platform-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": "Companies", "description": "Create and manage your SMB users' companies." }, { "name": "Connections", "description": "Create new and manage existing data connections for a company." }, { "name": "Connection management", "description": "Configure UI and retrieve access tokens for authentication used by **Connections SDK**." }, { "name": "Webhooks", "description": "Create and manage webhooks that listen to Codat's events." }, { "name": "Integrations", "description": "Get a list of integrations supported by Codat and their logos." }, { "name": "Refresh data", "description": "Initiate data refreshes, view pull status and history." }, { "name": "Settings", "description": "Manage company profile configuration, sync settings, and API keys." }, { "name": "Push data", "description": "Initiate and monitor Create, Update, and Delete operations." }, { "name": "Supplemental data", "description": "Configure and pull additional data you can include in Codat's standard data types." }, { "name": "Custom data type", "description": "Configure and pull additional data types that are not included in Codat's standardized data model." } ], "paths": { "/companies": { "get": { "summary": "List companies", "tags": [ "Companies" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies" }, "examples": { "One company": { "value": { "results": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "My Test Company", "description": "My Test Company make testing software", "platform": "", "redirect": "https://link.codat.io/company/3fa85f64-5717-4562-b3fc-2c963f66afa6", "lastSync": "2022-01-01T12:30:00.000Z", "dataConnections": [ { "id": "51baa045-4836-4317-a42e-3542e991e581", "integrationId": "1c312d69-e638-46d4-ad31-72e6c3ba8390", "integrationKey": "vjms", "sourceId": "396c3158-5dd7-481b-a7c4-a795ca31792b", "platformName": "Pandle", "linkUrl": "https://link-api.codat.io/companies/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections/51baa045-4836-4317-a42e-3542e991e581/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-01-01T11:30:00Z", "createdByUserName": "Mike Smith" } ], "pageNumber": 1, "pageSize": 100, "totalResults": 1, "_links": { "current": { "href": "/companies?page=1&pageSize=100" }, "self": { "href": "/companies" } } } }, "List of Companies": { "value": { "results": [ { "id": "d1568dde-adf6-11ed-afa1-0242ac120002", "name": "Technicalium", "description": "Technology services, including web and app design and development", "platform": "", "redirect": "https://link.codat.io/company/d1568dde-adf6-11ed-afa1-0242ac120002", "lastSync": "2022-01-01T12:30:00.000Z", "dataConnections": [ { "id": "51baa045-4836-4317-a42e-3542e991e581", "integrationId": "1c312d69-e638-46d4-ad31-72e6c3ba8390", "integrationKey": "vjms", "sourceId": "396c3158-5dd7-481b-a7c4-a795ca31792b", "platformName": "Pandle", "linkUrl": "https://link-api.codat.io/companies/d1568dde-adf6-11ed-afa1-0242ac120002/connections/51baa045-4836-4317-a42e-3542e991e581/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-01-01T11:30:00Z", "createdByUserName": "Joe Bloggs" }, { "id": "096db70b-78de-4ff0-aa98-299cb5fe17a0", "name": "Godata", "description": "A new digital agency with a passion for creating amazing digital experiences", "platform": "", "redirect": "https://link.codat.io/company/096db70b-78de-4ff0-aa98-299cb5fe17a0", "lastSync": "2022-01-01T12:30:00.000Z", "dataConnections": [ { "id": "a70bc148-dc21-46b2-a257-d9c58ac15cbb", "integrationId": "1c312d69-e638-46d4-ad31-72e6c3ba8390", "integrationKey": "vjms", "sourceId": "396c3158-5dd7-481b-a7c4-a795ca31792b", "platformName": "Pandle", "linkUrl": "https://link-api.codat.io/companies/096db70b-78de-4ff0-aa98-299cb5fe17a0/connections/a70bc148-dc21-46b2-a257-d9c58ac15cbb/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-01-01T11:30:00Z", "createdByUserName": "Mike Smith" } ], "pageNumber": 1, "pageSize": 100, "totalResults": 2, "_links": { "current": { "href": "/companies?page=1&pageSize=100" }, "self": { "href": "/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" } }, "operationId": "list-companies", "description": "The *List companies* endpoint returns a list of [companies] associated to your instances.\n\nA [company](https://docs.codat.io/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ] }, "post": { "summary": "Create company", "tags": [ "Companies" ], "operationId": "create-company", "responses": { "200": { "description": "OK", "content": { "application/json": { "x-speakeasy-usage-example": true, "schema": { "$ref": "#/components/schemas/Company" }, "examples": { "With no description": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Technicalium", "description": "", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18.1950523Z", "createdByUserName": "Dan Tzabar" } }, "With a description": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Technicalium", "description": "Technology services, including web and app design and development", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18.1950523Z", "createdByUserName": "Dan Tzabar" } }, "With a tag": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Technicalium", "description": "", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18.1950523Z", "createdByUserName": "Dan Tzabar", "tags": { "region": "us" } } } } } } }, "400": { "$ref": "#/components/responses/Bad-Request" }, "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" } }, "description": "Use the *Create company* endpoint to create a new [company](https://docs.codat.io/platform-api#/schemas/Company) that represents your customer in Codat. \n\nA [company](https://docs.codat.io/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n\nIf forbidden characters (see `name` pattern) are present in the request, a company will be created with the forbidden characters removed. For example, `Company (Codat[1])` with be created as `Company Codat1`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRequestBody" }, "examples": { "With no description": { "value": { "name": "Technicalium" } }, "With a description": { "value": { "name": "Technicalium", "description": "Technology services, including web and app design and development" } } } } } } } }, "/companies/{companyId}": { "get": { "summary": "Get company", "operationId": "get-company", "description": "The *Get company* endpoint returns a single company for a given `companyId`.\n\nA [company](https://docs.codat.io/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "tags": [ "Companies" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" }, "examples": { "Simple company": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "My First Company", "description": "", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18Z", "createdByUserName": "Dan Tzabar" } } } } } }, "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" } } }, "delete": { "summary": "Delete a company", "operationId": "delete-company", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "description": "The *Delete company* endpoint permanently deletes a [company](https://docs.codat.io/platform-api#/schemas/Company), its [connections](https://docs.codat.io/platform-api#/schemas/Connection) and any cached data. This operation is irreversible.\n\nA [company](https://docs.codat.io/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n", "tags": [ "Companies" ], "responses": { "204": { "description": "No Content" }, "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" } } }, "put": { "summary": "Update company", "description": "Use the *Update company* endpoint to update both the name and description of the company. \n\nA [company](https://docs.codat.io/platform-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/platform-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.", "operationId": "update-company", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "tags": [ "Companies" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "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": { "$ref": "#/components/schemas/CompanyRequestBody" }, "examples": { "Update name": { "value": { "name": "New Name" } }, "Update description": { "value": { "name": "Same name", "description": "Additional documents required" } } } } } } } }, "/companies/{companyId}/products/{productIdentifier}": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/productIdentifier" } ], "put": { "summary": "Add product", "operationId": "add-product", "x-speakeasy-name-override": "add-product", "description": "Use the *Add product* endpoint to enable a product for the company specified by `companyId`.\n\n> Note: This feature is currently in alpha and available only to participants in the development program.", "tags": [ "Companies" ], "responses": { "204": { "description": "OK" }, "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" } } }, "delete": { "summary": "Remove product", "operationId": "remove-product", "x-speakeasy-name-override": "remove-product", "description": "Use the *Remove product* endpoint to disable a product for the company specified by `companyId`.\n\n> Note: This feature is currently in alpha and available only to participants in the development program.", "tags": [ "Companies" ], "responses": { "204": { "description": "OK" }, "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": { "get": { "summary": "List connections", "description": "List the connections for a company.", "operationId": "list-connections", "tags": [ "Connections" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connections" }, "examples": { "Connections": { "value": { "results": [ { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } ], "pageNumber": 0, "pageSize": 0, "totalResults": 0, "_links": { "self": { "href": "string" }, "current": { "href": "string" }, "next": { "href": "string" }, "previous": { "href": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/Malformed-Query" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "post": { "summary": "Create connection", "description": "Creates a connection for the company by providing a valid `platformKey`. \n\nUse the [List Integrations](https://docs.codat.io/platform-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}": { "get": { "summary": "Get connection", "operationId": "get-connection", "description": "Returns a specific connection for a company when valid identifiers are provided. If the identifiers are for a deleted company and/or connection, a not found response is returned.", "tags": [ "Connections" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "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" } } }, "delete": { "summary": "Delete connection", "operationId": "delete-connection", "description": "Revoke and remove a connection from a company.\nThis operation is not reversible. The end user would need to reauthorize a new data connection if you wish to view new data for this company.", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "tags": [ "Connections" ], "responses": { "200": { "description": "OK" }, "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" } } }, "patch": { "summary": "Unlink connection", "description": "This allows you to deauthorize a connection, without deleting it from Codat. This means you can still view any data that has previously been pulled into Codat, and also lets you re-authorize in future if your customer wishes to resume sharing their data.", "operationId": "unlink-connection", "x-speakeasy-name-override": "unlink", "tags": [ "Connections" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "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": { "$ref": "#/components/schemas/UpdateConnectionStatus" }, "examples": { "Example": { "value": { "status": "Unlinked" } } } } }, "description": "" } } }, "/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": "" } } }, "/companies/{companyId}/connectionManagement/accessToken": { "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "get": { "summary": "Get access token", "operationId": "get-connection-management-access-token", "x-speakeasy-name-override": "get-access-token", "tags": [ "Connection management" ], "description": "Use the *Get access token* endpoint to retrieve a new access token for use with the [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management). The token is only valid for one hour and applies to a single company.\n\nThe embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) lets your customers control access to their data by allowing them to manage their existing connections.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionManagementAccessToken" }, "examples": { "Access token": { "value": { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" } } } } } }, "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" } } } }, "/connectionManagement/corsSettings": { "get": { "summary": "Get CORS settings", "operationId": "get-connection-management-cors-settings", "x-speakeasy-group": "connection-management.cors-settings", "tags": [ "Connection management" ], "description": "The *Get CORS settings* endpoint returns the allowed origins (i.e. your domains) you want to allow cross-origin resource sharing ([CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)) with Codat. \n\nEnabling CORS with Codat is required by our embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) to access Codat's API endpoints.\n\nThe embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) lets your customers control access to their data by allowing them to manage their existing connections.", "responses": { "200": { "$ref": "#/components/responses/ConnectionManagementAllowedOrigins" }, "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": "Set CORS settings", "operationId": "set-connection-management-cors-settings", "x-speakeasy-name-override": "set", "x-speakeasy-group": "connection-management.cors-settings", "tags": [ "Connection management" ], "description": "The *Set CORS settings* endpoint allows you to register allowed origins (i.e. your domains) for use in cross-origin resource sharing ([CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)).\n \nEnabling CORS with Codat is required by our embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) to access Codat's API endpoints. \n\nThe embeddable [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) lets your customers control access to their data by allowing them to manage their existing connections.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionManagementAllowedOrigins" }, "examples": { "Allowed origins": { "$ref": "#/components/examples/connectionManagementAllowedOriginsResponse" } } } } }, "responses": { "200": { "$ref": "#/components/responses/ConnectionManagementAllowedOrigins" }, "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}/data/all": { "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "post": { "summary": "Refresh all data", "operationId": "refresh-company-data", "x-speakeasy-name-override": "all", "responses": { "204": { "description": "No Content" }, "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" } }, "description": "Refreshes all data types with `fetch on first link` set to `true` for a given company.\n\nThis is an asynchronous operation, and will bring updated data into Codat from the linked integration for you to view.\n\n[Read more](https://docs.codat.io/core-concepts/data-type-settings) about data type settings and `fetch on first link`.", "tags": [ "Refresh data" ] } }, "/companies/{companyId}/data/queue/{dataType}": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/dataType" } ], "post": { "summary": "Refresh data type", "operationId": "refresh-data-type", "x-speakeasy-name-override": "by-data-type", "description": "Refreshes a given data type for a given company.\n\nThis is an asynchronous operation, and will bring updated data into Codat from the linked integration for you to view.", "tags": [ "Refresh data" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "connectionId", "description": "Optionally, provide a data connection id to only queue pull operations on that connection." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullOperation" } } } }, "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}/dataStatus": { "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "get": { "summary": "Get data status", "operationId": "get-company-data-status", "description": "Get the state of each data type for a company", "tags": [ "Refresh data" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStatuses" }, "examples": { "Example": { "value": { "accountTransactions": { "dataType": "accountTransactions", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "balanceSheet": { "dataType": "balanceSheet", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "bankAccounts": { "dataType": "bankAccounts", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "bankTransactions": { "dataType": "bankTransactions", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "billCreditNotes": { "dataType": "billCreditNotes", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "billPayments": { "dataType": "billPayments", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "bills": { "dataType": "bills", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "cashFlowStatement": { "dataType": "cashFlowStatement", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "chartOfAccounts": { "dataType": "chartOfAccounts", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "company": { "dataType": "company", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "creditNotes": { "dataType": "creditNotes", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "customers": { "dataType": "customers", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "directCosts": { "dataType": "directCosts", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "directIncomes": { "dataType": "directIncomes", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "invoices": { "dataType": "invoices", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "itemReceipts": { "dataType": "itemReceipts", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "items": { "dataType": "items", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "journalEntries": { "dataType": "journalEntries", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "journals": { "dataType": "journals", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "paymentMethods": { "dataType": "paymentMethods", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "payments": { "dataType": "payments", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "profitAndLoss": { "dataType": "profitAndLoss", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "purchaseOrders": { "dataType": "purchaseOrders", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "salesOrders": { "dataType": "salesOrders", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "suppliers": { "dataType": "suppliers", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "taxRates": { "dataType": "taxRates", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "trackingCategories": { "dataType": "trackingCategories", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "transfers": { "dataType": "transfers", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "banking-accountBalances": { "dataType": "banking-accountBalances", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "banking-accounts": { "dataType": "banking-accounts", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "banking-transactionCategories": { "dataType": "banking-transactionCategories", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "banking-transactions": { "dataType": "banking-transactions", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-companyInfo": { "dataType": "commerce-companyInfo", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-customers": { "dataType": "commerce-customers", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-disputes": { "dataType": "commerce-disputes", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-locations": { "dataType": "commerce-locations", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-orders": { "dataType": "commerce-orders", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-paymentMethods": { "dataType": "commerce-paymentMethods", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-payments": { "dataType": "commerce-payments", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-productCategories": { "dataType": "commerce-productCategories", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-products": { "dataType": "commerce-products", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-taxComponents": { "dataType": "commerce-taxComponents", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" }, "commerce-transactions": { "dataType": "commerce-transactions", "lastSuccessfulSync": "2022-01-01T00:00:00.000Z", "currentStatus": "Complete", "latestSyncId": "d03b6979-eb3b-447a-a27a-13cf457a9f48", "latestSuccessfulSyncId": "6883bba8-514d-423f-ba7f-c38285a80b7f" } } } } } } }, "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}/data/history": { "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "get": { "summary": "List pull operations", "tags": [ "Refresh data" ], "operationId": "list-pull-operations", "x-speakeasy-name-override": "list-pull-operations", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullOperations" }, "examples": { "Example": { "value": { "results": [ { "id": "97d60846-f07a-4d42-b5a0-0bdcc6ebf56b", "companyId": "4645bd78-8988-45bc-ac9e-67ba5df6e4e5", "connectionId": "51baa045-4836-4317-a42e-3542e991e581", "dataType": "invoices", "status": "Initial", "requested": "2022-11-14T11:18:37.2798351Z", "progress": 10, "isCompleted": false, "isErrored": false } ], "_links": { "current": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/data/history?page=1&pageSize=2" }, "self": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/data/history" }, "next": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/data/history?page=2&pageSize=2" } }, "pageNumber": 0, "pageSize": 0, "totalResults": 0 } } } } } }, "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" } }, "description": "Gets the pull operation history (datasets) for a given company.", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ] } }, "/companies/{companyId}/data/history/{datasetId}": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/datasetId" } ], "get": { "summary": "Get pull operation", "operationId": "get-pull-operation", "x-speakeasy-name-override": "get-pull-operation", "tags": [ "Refresh data" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullOperation" }, "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" } }, "description": "Retrieve information about a single dataset or pull operation." } }, "/rules": { "get": { "summary": "List webhooks (legacy)", "operationId": "list-rules", "description": "Use the *List webhooks (legacy)* endpoint to retrieve all existing rule-based webhooks for your client.\n\n**Note:** This endpoint has been deprecated. Please use the [*List webhook consumers*](https://docs.codat.io/platform-api#/operations/list-webhook-consumers) endpoint for listing webhooks moving forward.", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "deprecated": true, "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook/definitions/webhooks" }, "examples": { "Example": { "value": { "results": [ { "id": "fcfbfe0b-fe73-47ed-a7fe-0018567f5da2", "type": "DataConnectionStatusChanged", "notifiers": { "emails": [], "webhook": "https://webhook.site/6d385ea9-bcf9-48e4-9103-1958ccb54997" } } ], "pageNumber": 1, "pageSize": 100, "totalResults": 1, "_links": { "current": { "href": "/rules?page=1&pageSize=100" }, "self": { "href": "/rules" } } } } } } } }, "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 webhook (legacy)", "description": "Use the *Create webhooks (legacy)* endpoint to create a rule-based webhook for your client.\n\n**Note:** This endpoint has been deprecated. Please use the [*Create webhook consumer*](https://docs.codat.io/platform-api#/operations/create-webhook-consumer) endpoint to create a webhook moving forward.", "operationId": "create-rule", "deprecated": true, "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "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" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook/definitions/createRule" }, "examples": { "Company data connection status changed": { "value": { "type": "DataConnectionStatusChanged", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } }, "New company synchronized": { "value": { "type": "New company synchronised", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } }, "Data sync completed": { "value": { "type": "Data sync completed", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } }, "Dataset data changed": { "value": { "type": "Dataset data changed", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } }, "Dataset status has changed to an error state": { "value": { "type": "Data Sync Status Changed To Error", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } }, "Push operation status has changed": { "value": { "type": "Push Operation Status Changed", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } }, "Push operation has timed out": { "value": { "type": "Push Operation Timed Out", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } }, "Account categories updated": { "value": { "type": "Account Categories Updated", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } }, "Sync Connection Deleted": { "value": { "type": "Sync Connection Deleted", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } } } } }, "description": "Create a webhook with the given configuration." } } }, "/rules/{ruleId}": { "parameters": [ { "$ref": "#/components/parameters/ruleId" } ], "get": { "summary": "Get webhook (legacy)", "operationId": "get-webhook", "description": "Use the *Get webhook (legacy)* endpoint to retrieve a specific webhook for your client.\n\n**Note:** This endpoint has been deprecated. Please use the [*List webhook consumers*](https://docs.codat.io/platform-api#/operations/list-webhook-consumers) endpoint for listing webhooks moving forward.", "deprecated": true, "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "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" } } } }, "/webhooks": { "get": { "summary": "List webhook consumers", "operationId": "list-webhook-consumers", "x-speakeasy-name-override": "list-consumers", "description": "Use the *List webhook consumers* endpoint to return a list of all webhook consumers that currently exist for your client.\n\n[Webhook consumer](https://docs.codat.io/platform-api#/schemas/WebhookConsumer) is an HTTP endpoint that you configure to subscribe to specific events. See our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview).", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConsumer/definitions/webhookConsumers" }, "examples": { "Webhook consumers": { "value": { "results": [ { "id": "12571faf-0898-47e7-afdd-0fe9eb0a9bf5", "url": "https://example.com/webhoook-consumers/sync-complete", "eventTypes": [ "DataSyncCompleted" ], "disabled": false }, { "id": "ca3cac86-7925-4759-abc2-96405780fdfa", "url": "https://example.com/webhoook-consumers/dataset-changed", "eventTypes": [ "DatasetDataChanged" ], "disabled": true } ] } } } } } }, "400": { "$ref": "#/components/responses/Bad-Request" }, "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" } } }, "post": { "summary": "Create webhook consumer", "operationId": "create-webhook-consumer", "x-speakeasy-name-override": "create-consumer", "description": "Use the *Create webhook consumer* endpoint to create a new webhook consumer that will listen to messages we send you.\n\n[Webhook consumer](https://docs.codat.io/platform-api#/schemas/WebhookConsumer) is an HTTP endpoint that you configure to subscribe to specific events. See our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview).\n\n### Tips and traps\n- The number of webhook consumers you can create is limited to 50. If you have reached the maximum number of consumers, use the [*Delete webhook consumer*](https://docs.codat.io/platform-api#/operations/delete-webhook-consumer) endpoint to delete an unused consumer first.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConsumer/definitions/webhookConsumerPrototype" }, "examples": { "Subscribe consumer to one or more event types": { "value": { "url": "https://example.com/webhoook-consumer", "eventTypes": [ "DataSyncCompleted", "Dataset data changed" ] } }, "Subscribe consumer with disabled endpoint": { "value": { "url": "https://example.com/webhoook-consumer", "eventTypes": [ "DataSyncCompleted" ], "disabled": true } } } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConsumer" }, "examples": { "Subscribe consumer to one or more event types": { "value": { "id": "12571faf-0898-47e7-afdd-0fe9eb0a9bf5", "url": "https://example.com/webhoook-consumer", "eventTypes": [ "DataSyncCompleted", "DatasetDataChanged" ], "disabled": false } }, "Subscribe consumer with disabled endpoint": { "value": { "id": "12571faf-0898-47e7-afdd-0fe9eb0a9bf5", "url": "https://example.com/webhoook-consumer", "eventTypes": [ "DataSyncCompleted" ], "disabled": true } } } } } }, "400": { "$ref": "#/components/responses/Bad-Request" }, "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" } } } }, "/webhooks/{webhookId}": { "parameters": [ { "$ref": "#/components/parameters/webhookId" } ], "delete": { "summary": "Delete webhook consumer", "operationId": "delete-webhook-consumer", "x-speakeasy-name-override": "delete-consumer", "description": "Use the *Delete webhook consumer* endpoint to delete an existing webhoook consumer, providing its valid `id` as a parameter.\n\n[Webhook consumer](https://docs.codat.io/platform-api#/schemas/WebhookConsumer) is an HTTP endpoint that you configure to subscribe to specific events. See our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview).", "tags": [ "Webhooks" ], "responses": { "204": { "description": "No content" }, "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" } } } }, "/webhooks/integrationKeys/zapier": { "post": { "summary": "Rotate Zapier key", "operationId": "rotate-zapier-key", "x-speakeasy-ignore": true, "description": "The *Rotate Zapier key* endpoint returns the Zapier integration key needed to configure Zaps triggered by Codat's webhooks. \n\nIf a key has already been created, calling this will revoke that existing key.\n\nThe key changes each time this endpoint is called. If you are already using our Zapier integration and called this endpoint again, you need to reauthenticate using the latest integration key returned in the response.\n\nOur Zapier integration makes it simple for you to set up and receive user notifications in your preferred ways, such as via email or Slack. See our [Zapier documentation](https://docs.codat.io/using-the-api/webhooks/zapier-integration) for detailed instructions on setting up this integration.\n\n", "tags": [ "Webhooks" ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookZapierKey" }, "examples": { "Integration key": { "value": { "key": "sk_integ_WM4dfoK1nKZnDE_kceze6hWDjbRwOZwG.us" } } } } } }, "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" } } } }, "/integrations": { "get": { "summary": "List integrations", "description": "List your available integrations", "tags": [ "Integrations" ], "operationId": "list-integrations", "responses": { "200": { "description": "OK", "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" } }, "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ] } }, "/integrations/{platformKey}": { "parameters": [ { "$ref": "#/components/parameters/platformKey" } ], "get": { "summary": "Get integration", "tags": [ "Integrations" ], "operationId": "get-integration", "description": "Get single integration, by platformKey", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } } }, "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" } } } }, "/integrations/{platformKey}/branding": { "parameters": [ { "$ref": "#/components/parameters/platformKey" } ], "get": { "summary": "Get branding", "tags": [ "Integrations" ], "operationId": "get-integrations-branding", "x-speakeasy-name-override": "get-branding", "description": "Get branding for platform.", "responses": { "200": { "description": "OK", "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" } } } }, "/profile": { "get": { "summary": "Get profile", "tags": [ "Settings" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "examples": {} } } }, "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" } }, "operationId": "get-profile", "x-speakeasy-name-override": "get-profile", "description": "Fetch your Codat profile." }, "put": { "summary": "Update profile", "operationId": "update-profile", "x-speakeasy-name-override": "update-profile", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "examples": {} } } }, "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" } }, "tags": [ "Settings" ], "description": "Update your Codat profile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "examples": {} } }, "description": "All fields should be included when updating your profile." } } }, "/profile/syncSettings": { "get": { "summary": "Get sync settings", "tags": [ "Settings" ], "operationId": "get-profile-syncSettings", "x-speakeasy-name-override": "get-sync-settings", "description": "Retrieve the [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings) for your client. This includes how often data types should be queued to be updated, and how much history should be fetched.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSettings" }, "examples": { "Example": { "value": { "clientId": "367f7975-267b-439b-90c6-a6040ee680f3", "settings": [ { "dataType": "invoices", "fetchOnFirstLink": true, "syncSchedule": 24, "syncOrder": 0, "syncFromUtc": "2020-01-01T12:00:00.000Z", "syncFromWindow": 24, "monthsToSync": 24, "isLocked": true } ], "overridesDefaults": true } } } } } }, "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" } } }, "post": { "summary": "Update all sync settings", "description": "Update sync settings for all data types.", "tags": [ "Settings" ], "operationId": "update-profile-syncSettings", "x-speakeasy-name-override": "update-sync-settings", "responses": { "204": { "description": "No Content" }, "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" } }, "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "clientId": { "$ref": "#/components/schemas/ClientId" }, "settings": { "type": "array", "items": { "$ref": "#/components/schemas/SyncSetting" } }, "overridesDefaults": { "type": "boolean", "default": true, "description": "Set to `True` if you want to override default [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings)." } }, "required": [ "clientId", "settings", "overridesDefaults" ] } ], "type": "object" } } }, "description": "Include a `syncSetting` object for each data type.\n`syncFromWindow`, `syncFromUTC` & `monthsToSync` only need to be included if you wish to set a value for them." } } }, "/apiKeys": { "get": { "summary": "List API keys", "description": "Use the *List API keys* endpoint to return a list of all API keys that currently exist for your client. This includes keys created via the Portal UI or the *Create API keys* endpoint.\n\n[API keys](https://docs.codat.io/platform-api#/schemas/apiKeys) are tokens used to control access to the API. Include this token in the `Authorization` header parameter when making API calls, following the word \"Basic\" and a space with your API key.\n\nYou can [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat and managing API keys via the Portal UI or API.", "operationId": "list-api-keys", "x-speakeasy-name-override": "list-api-keys", "tags": [ "Settings" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeys" }, "examples": { "Example": { "value": { "results": [ { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "apiKey": "ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd", "createdDate": "2022-04-11T13:49:37Z" }, { "id": "c438836a-61fe-443f-8a19-24cc18be21e4", "name": "azure-invoice-finance-processor", "apiKey": "ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd", "createdDate": "2022-04-23T09:43:48Z" } ] } } } } } }, "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" } } }, "post": { "summary": "Create API key", "operationId": "create-api-key", "x-speakeasy-name-override": "create-api-key", "description": "Use the *Create API keys* endpoint to generate a new API key for your client.\n\n[API keys](https://docs.codat.io/platform-api#/schemas/apiKeys) are tokens used to control access to the API. Include this token in the `Authorization` header parameter when making API calls, following the word \"Basic\" and a space with your API key.\n\nYou can [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat and managing API keys via the Portal UI or API.\n\n### Tips and pitfalls\n\n* Your first API key is created for you. Access this key via [Codat's Portal](https://app.codat.io/developers/api-keys).\n* If you require multiple API keys, perform multiple calls to the *Create API keys* endpoint. \n* The number of API keys is limited to 10. If you have reached the maximum amount of keys, use the *Delete API key* endpoint to delete an unused key first.", "tags": [ "Settings" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKey" }, "examples": { "Create API key with name": { "value": { "name": "azure-invoice-finance-processor" } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDetails" }, "examples": { "API key details": { "value": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "apiKey": "ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd", "createdDate": "2022-04-11T13:49:37Z" } }, "API key details with name": { "value": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "azure-invoice-finance-processor", "apiKey": "ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd", "createdDate": "2022-04-11T13:49:37Z" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Max length for name reached": { "value": { "statusCode": 400, "service": "PublicApi", "error": "Max string length (50) for `name` reached.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Max length for name reached": { "value": { "statusCode": 400, "service": "PublicApi", "error": "Maximum number of API keys reached. To create a new API key, delete an unused key and try again.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/apiKeys/{apiKeyId}": { "delete": { "summary": "Delete API key", "operationId": "delete-api-key", "x-speakeasy-name-override": "delete-api-key", "parameters": [ { "name": "apiKeyId", "in": "path", "required": true, "schema": { "type": "string", "example": "8a210b68-6988-11ed-a1eb-0242ac120002" }, "description": "Unique identifier for api key." } ], "description": "Use the *Delete API keys* endpoint to delete an existing API key, providing its valid `id` as a parameter. Note that this operation is not reversible.\n\n[API keys](https://docs.codat.io/platform-api#/schemas/apiKeys) are tokens used to control access to the API. Include this token in the `Authorization` header parameter when making API calls, following the word \"Basic\" and a space with your API key.\n\nYou can [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat and managing API keys via the Portal UI or API.\n\n### Tips and pitfalls\n\n* It is possible to delete the last remaining API key. If this happens, a new key can be created via the [API key management page](https://app.codat.io/developers/api-keys) of the Portal.\n* It is possible to delete the API key used to authenticate the *Delete API key* request.", "tags": [ "Settings" ], "responses": { "204": { "description": "No Content", "$ref": "#/components/responses/Too-Many-Requests" }, "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}/options/{dataType}": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/dataType" } ], "get": { "summary": "Get push options", "tags": [ "Push data" ], "operationId": "get-create-update-model-options-by-data-type", "x-speakeasy-name-override": "get-model-options", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOption" }, "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" } }, "description": "This is the generic documentation for creation and updating of data. See the equivalent endpoint for a given data type for more specific information. \n\nBefore pushing data into accounting software, it is often necessary to collect some details from the user as to how they would like the data to be inserted. This includes names and amounts on transactional entities, but also factors such as categorisation of entities, which is often handled differently between different accounting software. A good example of this is specifying where on the balance sheet/profit and loss reports the user would like a newly-created nominal account to appear.\n\nCodat tries not to limit users to pushing to a very limited number of standard categories, so we have implemented \"options\" endpoints, which allow us to expose to our clients the fields which are required to be pushed for a specific linked company, and the options which may be selected for each field.\n\n\n> **Supported Integrations**\n> \n> Check out our [coverage explorer](https://knowledge.codat.io/) for integrations that support push (POST/PUT methods)." } }, "/companies/{companyId}/push": { "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "get": { "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "summary": "List push operations", "tags": [ "Push data" ], "operationId": "get-company-push-history", "x-speakeasy-name-override": "list-operations", "description": "The **List push operations** endpoint returns a list of [push operations](/using-the-api/push) performed on the company.\n\nWrite operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOperations" }, "examples": {} } } }, "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" } } } }, "/companies/{companyId}/push/{pushOperationKey}": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "schema": { "type": "string", "format": "uuid" }, "name": "pushOperationKey", "in": "path", "required": true, "description": "Push operation key." } ], "get": { "summary": "Get push operation", "tags": [ "Push data" ], "operationId": "get-push-operation", "x-speakeasy-name-override": "get-operation", "description": "The **Get push operation** endpoint returns a specific [push operation](/using-the-api/push) identified by the `pushOperationKey` that was performed on the company.\n\nWrite operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOperation" }, "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" } } } }, "/integrations/{platformKey}/dataTypes/{dataType}/supplementalDataConfig": { "parameters": [ { "$ref": "#/components/parameters/platformKey" }, { "name": "dataType", "in": "path", "required": true, "description": "Supported supplemental data data type.", "schema": { "x-internal": true, "type": "string", "description": "Data types that support supplemental data", "enum": [ "chartOfAccounts", "bills", "company", "creditNotes", "customers", "invoices", "items", "journalEntries", "suppliers", "taxRates", "commerce-companyInfo", "commerce-customers", "commerce-disputes", "commerce-locations", "commerce-orders", "commerce-payments", "commerce-paymentMethods", "commerce-products", "commerce-productCategories", "commerce-taxComponents", "commerce-transactions" ], "example": "invoices" } } ], "put": { "summary": "Configure", "description": "The *Configure* endpoint allows you to maintain or change configuration required to return supplemental data for each integration and data type combination.\n\n[Supplemental data](https://docs.codat.io/using-the-api/additional-data) is additional data you can include in Codat's standard data types.\n\n**Integration-specific behaviour**\nSee the *examples* for integration-specific frequently requested properties.", "operationId": "configure-supplemental-data", "x-speakeasy-name-override": "configure", "tags": [ "Supplemental data" ], "responses": { "200": { "description": "OK" }, "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": { "$ref": "#/components/schemas/SupplementalDataConfiguration" }, "examples": { "Xero - Accounts": { "value": { "yourKeyNameForAccounts": { "dataSource": "/Accounts", "pullData": { "yourNameForTaxType": "TaxType", "yourNameForSystemAccount": "SystemAccount" } } } }, "Xero - Invoices": { "value": { "yourKeyNameForInvoices": { "dataSource": "/Invoices", "pullData": { "yourNameForExpectedPaymentDate": "ExpectedPaymentDate", "yourNameForHasAttachments": "HasAttachments" } } } }, "Xero - Items": { "value": { "yourKeyNameForItems": { "dataSource": "/Items", "pullData": { "yourNameForQuantityOnHand": "QuantityOnHand", "yourNameForTotalCostPool": "TotalCostPool" } } } }, "Xero - Contacts": { "value": { "yourKeyNameForContacts": { "dataSource": "/Contacts", "pullData": { "yourNameForBankAccounts": "BankAccountDetails" } } } }, "Xero - Tax rates": { "value": { "yourKeyNameForTaxRates": { "dataSource": "/TaxRates", "pullData": { "yourNameForCanApplyToLiabilities": "CanApplyToLiabilities", "yourNameForCanApplyToAssets": "CanApplyToAssets", "yourNameForCanApplyToEquity": "CanApplyToEquity", "yourNameForCanApplyToExpenses": "CanApplyToExpenses", "yourNameForCanApplyToRevenue": "CanApplyToRevenue" } } } }, "QBO - Customers": { "value": { "yourKeyNameForCustomers": { "dataSource": "/Customer", "pullData": { "yourNameForSalesTermRef": "SalesTermRef.value", "yourNameForParentRef": "ParentRef.value" } } } }, "QBO - Invoices": { "value": { "yourKeyNameForInvoices": { "dataSource": "/Invoice", "pullData": { "yourNameForSalesTermRef": "SalesTermRef.value" } } } } } } }, "description": "The configuration for the specified platform and data type." } }, "get": { "summary": "Get configuration", "description": "The *Get configuration* endpoint returns supplemental data configuration previously created for each integration and data type combination.\n\n[Supplemental data](https://docs.codat.io/using-the-api/additional-data) is additional data you can include in Codat's standard data types.", "operationId": "get-supplemental-data-configuration", "x-speakeasy-name-override": "get-configuration", "tags": [ "Supplemental data" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementalDataConfiguration" } } } }, "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" } } } }, "/integrations/{platformKey}/dataTypes/custom/{customDataIdentifier}": { "parameters": [ { "$ref": "#/components/parameters/platformKey" }, { "$ref": "#/components/parameters/customDataIdentifier" } ], "put": { "summary": "Configure custom data type", "description": "The *Configure custom data type* endpoint allows you to maintain or change the configuration required to return a custom data type for a specific integration. \n\nA [custom data type](https://docs.codat.io/using-the-api/custom-data) is an additional data type you can create that is not included in Codat's standardized data model.\n\n### Tips and traps\n\n- You can only configure a single custom data type for a single platform at a time. Use the endpoint multiple times if you need to configure it for multiple platforms. \n\n- You can only indicate a single data source for each customer data type. \n\n- Make your custom configuration as similar as possible to our standard data types so you can interact with them in exactly the same way.", "operationId": "configure-custom-data-type", "x-speakeasy-name-override": "configure", "tags": [ "Custom data type" ], "requestBody": { "description": "Custom data type configuration for the specified platform.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomDataTypeConfiguration" }, "examples": { "Dynamics 365 Business Central": { "value": { "dataSource": "api/purchaseOrders", "requiredData": { "currency": "$[*].currencyCode", "number": "$[*].number", "date": "$[*].orderDate", "totalexvat": "$[*].totalAmountExcludingTax", "totaltax": "$[*].totalTaxAmount", "vendor": "$[*].number" }, "keyBy": [ "$[*].id" ], "sourceModifiedDate": [ "$[*].lastModifiedDateTime" ] } }, "Xero Simple Record": { "value": { "dataSource": "/api.xro/2.0/Accounts", "requiredData": { "code": "$.Code", "accountId": "$.AccountID", "type": "$.Type", "SysAcc": "$.SystemAccount" }, "keyBy": [ "$.AccountID" ] } }, "Xero Mapping Arrays": { "value": { "dataSource": "/api.xro/2.0/Invoices", "requiredData": { "invNumber": "$.InvoiceNumber", "type": "$.Type", "InvoiceID": "$.InvoiceID", "lines": "$.LineItems[*]" }, "keyBy": [ "$.InvoiceID" ], "sourceModifiedDate": [ "$.UpdatedDateUTC" ] } }, "QuickBooks Online": { "value": { "dataSource": "/query?query=select * from Account", "requiredData": { "id": "$.Id", "Currentbal": "$.CurrentBalance", "SubAcc": "$.SubAccount" }, "keyBy": [ "$.Id" ], "sourceModifiedDate": [ "$.time" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomDataTypeConfiguration" }, "examples": { "Dynamics 365 Business Central": { "value": { "dataSource": "api/purchaseOrders", "requiredData": { "currency": "$[*].currencyCode", "number": "$[*].number", "date": "$[*].orderDate", "totalexvat": "$[*].totalAmountExcludingTax", "totaltax": "$[*].totalTaxAmount", "vendor": "$[*].number" }, "keyBy": [ "$[*].id" ], "sourceModifiedDate": [ "$[*].lastModifiedDateTime" ] } }, "Xero Simple Record": { "value": { "dataSource": "/api.xro/2.0/Accounts", "requiredData": { "code": "$.Code", "accountId": "$.AccountID", "type": "$.Type", "SysAcc": "$.SystemAccount" }, "keyBy": [ "$.AccountID" ] } }, "Xero Mapping Arrays": { "value": { "dataSource": "/api.xro/2.0/Invoices", "requiredData": { "invNumber": "$.InvoiceNumber", "type": "$.Type", "InvoiceID": "$.InvoiceID", "lines": "$.LineItems[*]" }, "keyBy": [ "$.InvoiceID" ], "sourceModifiedDate": [ "$.UpdatedDateUTC" ] } }, "QuickBooks Online": { "value": { "dataSource": "/query?query=select * from Account", "requiredData": { "id": "$.Id", "Currentbal": "$.CurrentBalance", "SubAcc": "$.SubAccount" }, "keyBy": [ "$.Id" ], "sourceModifiedDate": [ "$.time" ] } } } } } }, "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" } } }, "get": { "summary": "Get custom data configuration", "description": "The *Get custom data configuration* endpoint returns existing configuration details for the specified custom data type and integration pair you previously configured.\n\nA [custom data type](https://docs.codat.io/using-the-api/custom-data) is an additional data type you can create that is not included in Codat's standardized data model.", "operationId": "get-custom-data-type-configuration", "x-speakeasy-name-override": "get-configuration", "tags": [ "Custom data type" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomDataTypeRecords" } } } }, "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}/data/queue/custom/{customDataIdentifier}": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/customDataIdentifier" } ], "post": { "summary": "Refresh custom data type", "description": "The *Refresh custom data type* endpoint refreshes the specified custom data type for a given company. This is an asynchronous operation that will sync updated data from the linked integration into Codat for you to view.", "operationId": "refresh-custom-data-type", "x-speakeasy-name-override": "refresh", "tags": [ "Custom data type" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullOperation" } } } }, "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" }, "451": { "$ref": "#/components/responses/Legal-Reasons" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/data/custom/{customDataIdentifier}": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/customDataIdentifier" } ], "get": { "summary": "List custom data type records", "description": "The *List custom data type records* endpoint returns a paginated list of records pulled for the specified custom data type you previously configured.\n\nA [custom data type](https://docs.codat.io/using-the-api/custom-data) is an additional data type you can create that is not included in Codat's standardized data model.s endpoint returns a paginated list of records whose schema is defined [Configure custom data type](https://docs.codat.io/platform-api#/operations/configure-custom-data-type)", "operationId": "list-custom-data-type-records", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" } ], "tags": [ "Custom data type" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomDataTypeRecords" } } } }, "400": { "$ref": "#/components/responses/Bad-Request" }, "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" }, "451": { "$ref": "#/components/responses/Legal-Reasons" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } } }, "webhooks": { "company.created": { "post": { "description": "Called when a company is created in Codat.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyWebhook" }, "examples": { "Company created": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "type": "company.created", "generatedDate": "2024-08-08T17:10:34.015Z", "payload": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Bank of Dave", "description": "Requested a loan for refurb.", "redirect": "https://link.codat.io/company/0498e921-9b53-4396-a412-4f2f5983b0a2", "lastSync": "2022-01-01T12:00:00.000Z", "created": "2022-01-01T12:00:00.000Z", "tags": { "customerRegion": "us", "uid": "335a086e-8563-4b03-94e3-39544225ecb6" } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "company.deleted": { "post": { "description": "Called when a company is deleted in Codat.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyWebhook" }, "examples": { "Company deleted": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "eventType": "company.deleted", "generatedDate": "2024-08-08T17:10:34.015Z", "payload": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Bank of Dave", "description": "Requested a loan for refurb.", "redirect": "https://link.codat.io/company/0498e921-9b53-4396-a412-4f2f5983b0a2", "lastSync": "2022-01-01T12:00:00.000Z", "created": "2022-01-01T12:00:00.000Z", "tags": { "customerRegion": "uk", "uid": "f6b0c253-16c7-4da1-a0c5-9c871e9c9d6c" } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "connection.created": { "post": { "description": "Called when a connection is created by the SMB.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionWebhook" }, "examples": { "Connection created": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "type": "connection.created", "generatedDate": "2024-08-08T17:10:34.015Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Bank of Dave", "description": "internal_id_mxO7rLfo", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" }, "tags": { "customerRegion": "us", "uid": "335a086e-8563-4b03-94e3-39544225ecb6" } }, "connection": { "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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "PendingAuth", "lastSync": "2022-10-27T10:22:43.646Z", "created": "2022-10-27T09:53:29.000Z", "sourceType": "Banking" } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "connection.connected": { "post": { "description": "Called when a connection is successfully linked by the SMB.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionWebhook" }, "examples": { "Connection connected": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "type": "connection.connected", "generatedDate": "2024-08-08T17:10:34.015Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Bank of Dave", "description": "internal_id_mxO7rLfo", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" }, "tags": { "customerRegion": "us", "uid": "335a086e-8563-4b03-94e3-39544225ecb6" } }, "connection": { "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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.646Z", "created": "2022-10-27T09:53:29.000Z", "sourceType": "Banking" } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "connection.disconnected": { "post": { "description": "Called when a connection is disconnected either due to being unlinked or de-authorized by the SMB or integration.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionWebhook" }, "examples": { "Unlinked": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "type": "connection.disconnected", "generatedDate": "2024-08-08T17:10:34.015Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Bank of Dave", "description": "internal_id_mxO7rLfo", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" }, "tags": { "customerRegion": "us", "uid": "335a086e-8563-4b03-94e3-39544225ecb6" } }, "connection": { "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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Unlinked", "lastSync": "2022-10-27T10:22:43.646Z", "created": "2022-10-27T09:53:29.000Z", "sourceType": "Banking" } } } }, "De-authorized": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "type": "connection.disconnected", "generatedDate": "2024-08-08T17:10:34.015Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Bank of Dave", "description": "internal_id_mxO7rLfo", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" }, "tags": { "customerRegion": "us", "uid": "335a086e-8563-4b03-94e3-39544225ecb6" } }, "connection": { "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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Deauthorized", "lastSync": "2022-10-27T10:22:43.646Z", "created": "2022-10-27T09:53:29.000Z", "sourceType": "Banking", "dataConnectionErrors": [ { "statusCode": "401", "statusText": "The integration de-authorized access to the connection.", "errorMessage": "The integration de-authorized access to the connection.", "erroredOnUtc": "2022-12-27T09:53:29.000Z", "status": "Active" } ] } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "connection.reconnected": { "post": { "description": "Called when a connection is reconnected after becoming disconnected.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionWebhook" }, "examples": { "Reconnected": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "type": "connection.reconnected", "generatedDate": "2024-08-08T17:10:34.015Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Bank of Dave", "description": "internal_id_mxO7rLfo", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" }, "tags": { "customerRegion": "us", "uid": "335a086e-8563-4b03-94e3-39544225ecb6" } }, "connection": { "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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.646Z", "created": "2022-10-27T09:53:29.000Z", "sourceType": "Banking" } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "connection.deleted": { "post": { "description": "Called when a connection is deleted.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionWebhook" }, "examples": { "Deleted": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "type": "connection.deleted", "generatedDate": "2024-08-08T17:10:34.015Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Bank of Dave", "description": "internal_id_mxO7rLfo", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" }, "tags": { "customerRegion": "us", "uid": "335a086e-8563-4b03-94e3-39544225ecb6" } }, "connection": { "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/0498e921-9b53-4396-a412-4f2f5983b0a2/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.646Z", "created": "2022-10-27T09:53:29.000Z", "sourceType": "Banking" } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "read.completed": { "post": { "description": "Called when the fetch of data types for a product has completed.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadCompletedWebhook" }, "examples": { "Read completed": { "value": { "id": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "eventType": "read.completed", "generatedDate": "2022-10-23T00:00:00.000Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Toft stores", "description": "Requested early access to the new financing scheme.", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" } }, "modifiedFromDate": "2022-10-23T00:00:00.000Z", "dataTypes": [ { "connectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "dataType": "invoices", "recordsModified": false, "status": "Complete" } ] } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "read.completed.initial": { "post": { "description": "Called when the initial fetch of data types for a product has been completed.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadCompletedWebhook" }, "examples": { "Initial": { "value": { "id": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "eventType": "read.completed.initial", "generatedDate": "2022-10-23T00:00:00.000Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Toft stores", "description": "Requested early access to the new financing scheme.", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" } }, "modifiedFromDate": "2022-10-23T00:00:00.000Z", "dataTypes": [ { "connectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "dataType": "invoices", "recordsModified": false, "status": "Complete" } ] } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "{dataType}.write.successful": { "post": { "description": "Indicates that a `dataType` has been successfully created, updated, deleted, or had an attachment uploaded in the accounting software.\n\nCodat now refers to push operations as write requests.\n\nFor example, to subscribe to events where a bill is written into the accounting software, use the `bills.write.successful` webhook.\n\n### Supported data types and write types\n\n| `dataType` | Create | Update | Delete | UploadAttachment |\n|------------------|---------|---------|---------|------------------|\n| bankAccounts | ✅ | ✅ | - | - | \n| bankTransactions | ✅ | - | - | - |\n| billCreditNotes | ✅ | ✅ | - | ✅ | \n| billPayments | ✅ | - | ✅ | - | \n| bills | ✅ | ✅ | ✅ | ✅ | \n| chartOfAccounts | ✅ | - | - | - | \n| creditNotes | ✅ | ✅ | - | - | \n| customers | ✅ | ✅ | - | - | \n| directCosts | ✅ | - | ✅ | ✅ | \n| directIncomes | ✅ | - | - | ✅ | \n| invoices | ✅ | ✅ | ✅ | ✅ | \n| items | ✅ | - | - | - | \n| journalEntries | ✅ | - | ✅ | - | \n| journals | ✅ | - | - | - | \n| payments | ✅ | - | - | - | \n| purchaseOrders | ✅ | ✅ | - | - | \n| suppliers | ✅ | ✅ | - | - | \n| transfers | ✅ | - | - | ✅ | \n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataTypeWriteWebhook" }, "examples": { "Record": { "value": { "id": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "eventType": "{dataType}.write.successful", "generatedDate": "2023-05-03T10:00:23.000Z", "payload": { "id": "a9367074-b5c3-42c4-9be4-be129f43577e", "type": "Create", "referenceCompany": { "id": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "name": "Toft stores", "description": "cust_1MtJUT2eZvKYlo2CNaw2HvEv" }, "connectionId": "12571faf-0898-47e7-afdd-0fe9eb0a9bf5", "requestedOnDate": "2023-05-03T10:00:00.000Z", "completedOnDate": "2023-05-03T10:00:23.000Z", "status": "Success", "record": { "id": "bil_1Nispe2eZvKYlo2Cd31jOCgZ" } } } }, "Attachment": { "value": { "id": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "eventType": "{dataType}.write.successful", "generatedDate": "2023-05-03T10:00:23.000Z", "payload": { "id": "a9367074-b5c3-42c4-9be4-be129f43577e", "type": "UploadAttachment", "referenceCompany": { "id": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "name": "Toft stores", "description": "cust_1MtJUT2eZvKYlo2CNaw2HvEv" }, "connectionId": "12571faf-0898-47e7-afdd-0fe9eb0a9bf5", "requestedOnDate": "2023-05-03T10:00:00.000Z", "completedOnDate": "2023-05-03T10:00:23.000Z", "status": "Success", "record": { "id": "bil_1Nispe2eZvKYlo2Cd31jOCgZ" }, "attachmentId": "att_1AZtxr2eZvKYlo2CJDX8whov" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received." } } } }, "{dataType}.write.unsuccessful": { "post": { "description": "Indicates that a `dataType` has not been successfully created, updated, deleted, or had an attachment uploaded in the accounting software.\n\nCodat now refers to push operations as write requests.\n\nFor example, to subscribe to events where a bill is written into the accounting software, use the `bills.write.unsuccessful` webhook.\n\n### Supported data types and write types\n\n| `dataType` | Create | Update | Delete | UploadAttachment |\n|------------------|---------|---------|---------|------------------|\n| bankAccounts | ✅ | ✅ | - | - | \n| bankTransactions | ✅ | - | - | - |\n| billCreditNotes | ✅ | ✅ | - | ✅ | \n| billPayments | ✅ | - | ✅ | - | \n| bills | ✅ | ✅ | ✅ | ✅ | \n| chartOfAccounts | ✅ | - | - | - | \n| creditNotes | ✅ | ✅ | - | - | \n| customers | ✅ | ✅ | - | - | \n| directCosts | ✅ | - | ✅ | ✅ | \n| directIncomes | ✅ | - | - | ✅ | \n| invoices | ✅ | ✅ | ✅ | ✅ | \n| items | ✅ | - | - | - | \n| journalEntries | ✅ | - | ✅ | - | \n| journals | ✅ | - | - | - | \n| payments | ✅ | - | - | - | \n| purchaseOrders | ✅ | ✅ | - | - | \n| suppliers | ✅ | ✅ | - | - | \n| transfers | ✅ | - | - | ✅ | \n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataTypeWriteWebhook" }, "examples": { "Record": { "value": { "id": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "eventType": "{dataType}.write.unsuccessful", "generatedDate": "2023-05-03T10:00:23.000Z", "payload": { "id": "a9367074-b5c3-42c4-9be4-be129f43577e", "type": "Update", "referenceCompany": { "id": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "name": "Toft stores", "description": "cust_1MtJUT2eZvKYlo2CNaw2HvEv" }, "connectionId": "12571faf-0898-47e7-afdd-0fe9eb0a9bf5", "requestedOnDate": "2023-05-03T10:00:00.000Z", "completedOnDate": "2023-05-03T10:00:23.000Z", "status": "Failed" } } }, "Record timed out": { "value": { "id": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "eventType": "{dataType}.write.unsuccessful", "generatedDate": "2023-05-03T10:00:23.000Z", "payload": { "id": "a9367074-b5c3-42c4-9be4-be129f43577e", "type": "Delete", "referenceCompany": { "id": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "name": "Toft stores", "description": "cust_1MtJUT2eZvKYlo2CNaw2HvEv" }, "connectionId": "12571faf-0898-47e7-afdd-0fe9eb0a9bf5", "requestedOnDate": "2023-05-03T10:00:00.000Z", "completedOnDate": "2023-05-03T10:00:23.000Z", "status": "TimedOut" } } }, "Attachment": { "value": { "id": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "eventType": "{dataType}.write.unsuccessful", "generatedDate": "2023-05-03T10:00:23.000Z", "payload": { "id": "a9367074-b5c3-42c4-9be4-be129f43577e", "type": "UploadAttachment", "referenceCompany": { "id": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "name": "Toft stores", "description": "cust_1MtJUT2eZvKYlo2CNaw2HvEv" }, "connectionId": "12571faf-0898-47e7-afdd-0fe9eb0a9bf5", "requestedOnDate": "2023-05-03T10:00:00.000Z", "completedOnDate": "2023-05-03T10:00:23.000Z", "status": "TimedOut", "record": { "id": "bil_1Nispe2eZvKYlo2Cd31jOCgZ" } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received." } } } }, "client.rateLimit.reached": { "post": { "description": "Called when your client’s request count to Codat's API surpasses the allocated quota.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRateLimitWebhook" }, "examples": { "Reached": { "value": { "id": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "eventType": "client.rateLimit.reached", "generatedDate": "2024-09-01T00:00:00Z", "payload": { "dailyQuota": 12000, "quotaRemaining": 0, "expiryDate": "2024-09-01T12:14:14Z" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "client.rateLimit.reset": { "post": { "description": "Called when your client's rate limit quota is reset, allowing additional requests to Codat's API.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRateLimitWebhook" }, "examples": { "Reset": { "value": { "id": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "eventType": "client.rateLimit.reset", "generatedDate": "2024-09-01T00:00:00Z", "payload": { "dailyQuota": 12000, "quotaRemaining": 11993, "expiryDate": "2024-09-01T23:59:99Z" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Company data connection status changed": { "post": { "description": "Called anytime a data connection's status changes.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionStatusChangedWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Data sync completed": { "post": { "deprecated": true, "description": "Generated for each data type to indicate that data synchronization is successfully completed for that specific data type.\n\nThis event type has been deprecated. To replicate it, use the `read.completed` webhook and check if `payload.dataTypes[].status` is set to `Success` for all data types in the array.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSyncCompletedWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Dataset data changed": { "post": { "deprecated": true, "description": "Generated for each data type to indicate that dataset synchronization has completed and updated Codat's data cache through the creation of new records or a change to existing records.\n\nThis event type has been deprecated. To replicate it, use the `read.completed` webhook and verify that `payload.dataTypes[].status` is set to `Success` and `payload.dataTypes[].modifiedRecords` is `True` for any data type in the array.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetDataChangedWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Dataset status has changed to an error state": { "post": { "deprecated": true, "description": "Indicates that the synchronization of a dataset failed.\n\nThis event type has been deprecated.\nTo replicate it, use the `read.completed` webhook and check if `payload.dataTypes[].status` is set to any of the following statuses for any data type in the array:\n\n- `FetchError`\n- `MapError`\n- `InternalError`\n- `ProcessingError`\n- `ValidationError`\n- `AuthError`\n- `RateLimitError`\n- `PermissionsError`\n- `PrerequisiteNotMet`", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetStatusChangedErrorWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "New company synchronized": { "post": { "description": "Triggered after a new company has successfully synchronized at least one dataType for the first time.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewCompanySynchronizedWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Push operation status has changed": { "post": { "deprecated": true, "description": "Indicates that a create, update, or delete operation's status has changed.\n\nThis event type has been deprecated. Use either the `{dataType}.write.successful` or `{dataType}.write.unsuccessful` instead.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOperationStatusChangedWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Push operation has timed out": { "post": { "deprecated": true, "description": "Indicates that a create, update, or delete operation has timed out.\n\nThis event type has been deprecated.\nTo replicate it, use the `{dataType}.write.unsuccessful` webhook and check if `payload.status` is set to `TimedOut`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOperationTimedOutWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Client rate limit reached": { "post": { "deprecated": true, "description": "Called when your client’s requests to Codat's API exceed the allocated quota. \n\n**Note: This event type is deprecated. Developers should now use the `client.rateLimit.reached` event for handling rate limit notifications.**", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRateLimitReachedWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Client rate limit reset": { "post": { "deprecated": true, "description": "Called when the rate limit quota has reset for the client, and more requests to Codat's API are available.\n\nNote: This event type is deprecated. Developers should now use the `client.rateLimit.reset` event for handling rate limit notifications.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } } }, "components": { "schemas": { "ApiKeyDetails": { "title": "API key details", "description": "Details of the API key.", "type": "object", "allOf": [ { "properties": { "id": { "type": "string", "description": "Unique identifier for the API key.", "example": "e288a972-b402-4b21-93f9-b5335ae5679c" }, "name": { "type": "string", "maxLength": 50, "nullable": true, "description": "A meaningful name assigned to the API key.", "example": "azure-invoice-finance-processor" }, "apiKey": { "type": "string", "description": "The API key value used to make authenticated http requests.", "example": "ztHQGvnC4XN2CgUhaDWEG4ySLUJqWjp7zkbZkGHd" } } }, { "nullable": true, "description": "Datetime in UTC the API key was created. The created date will be null if the API key created before YYYY-MM-DD.", "title": "Created date", "type": "object", "x-internal": true, "properties": { "createdDate": { "$ref": "#/components/schemas/DateTime", "description": "The date the entity was created." } } } ] }, "ApiKeys": { "title": "API keys", "x-internal": true, "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyDetails" } } } }, "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" } ] }, "ClientId": { "title": "Client ID", "type": "string", "format": "uuid", "description": "Unique identifier for your client in Codat." }, "ClientRateLimitReachedWebhook": { "title": "Client rate limit reached webhook", "x-internal": true, "description": "Webhook request body for a client that has reached their rate limit.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientId" }, "ClientName": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/ClientName" }, "RuleId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/Message" }, "Data": { "$ref": "#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData" } }, "definitions": { "ClientRateLimitReachedWebhookData": { "type": "object", "title": "Client rate limit reached webhook data", "properties": { "DailyQuota": { "type": "integer", "description": "The number of available requests per day." }, "ExpiresUtc": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC when your daily quota is reset." } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Rate Limit Reached", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "The current daily rate limit quota of 1000 requests for bae71d36-ff47-420a-b4a6-f8c9ddf41140 has been reached.", "Data": { "DailyQuota": 1000, "ExpiresUtc": "2023-05-03T00:00:00Z" } } ] }, "ClientRateLimitResetWebhook": { "title": "Client rate limit reset webhook", "x-internal": true, "description": "Webhook request body for a client that has had their rate limit reset.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientId" }, "ClientName": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/ClientName" }, "RuleId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/Message" }, "Data": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/definitions/ClientRateLimitResetWebhookData" } }, "definitions": { "ClientRateLimitResetWebhookData": { "type": "object", "title": "Client rate limit reset webhook data", "properties": { "QuotaRemaining": { "type": "integer", "description": "Total number of requests remaining for your client.", "nullable": true }, "ResetReason": { "type": "string", "description": "The reason for your rate limit quota being reset." }, "DailyQuota": { "$ref": "#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/DailyQuota", "nullable": true }, "ExpiresUtc": { "$ref": "#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/ExpiresUtc", "nullable": true } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Rate Limit Reset", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "The current daily rate limit quota for client 30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e has been reset to 1000 requests.", "Data": { "QuotaRemaining": 1000, "ResetReason": "The quota was reset because it is a new day.", "DailyQuota": 1000, "ExpiresUtc": "2023-05-03T00:00:00Z" } } ] }, "ClientRateLimitWebhook": { "title": "Client rate limit webhook", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "description": "Unique identifier of the event." }, "eventType": { "type": "string", "description": "The type of event.", "examples": [ "client.rateLimit.reset", "client.rateLimit.reached" ] }, "generatedDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC the event was generated in Codat." }, "payload": { "$ref": "#/components/schemas/ClientRateLimitWebhook/definitions/clientRateLimitWebhookPayload" } }, "definitions": { "clientRateLimitWebhookPayload": { "title": "Client rate limit webhook payload", "type": "object", "properties": { "dailyQuota": { "type": "integer", "description": "The number of available requests per day." }, "quotaRemaining": { "type": "integer", "description": "Total number of requests remaining for your client." }, "expiryDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC when your daily quota is reset." } } } } }, "Companies": { "title": "Companies", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "Company": { "title": "Company", "description": "In Codat, a company represents a business sharing access to their data. Each company can have multiple [connections](https://docs.codat.io/platform-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/CompanyRequestBody/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/DateTime", "nullable": true }, "created": { "$ref": "#/components/schemas/DateTime" }, "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" } ] } ] }, "CompanyRequestBody": { "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" ] }, "CompanyWebhook": { "title": "Company 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": [ "company.created", "company.deleted" ] }, "generatedDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC the event was generated in Codat." }, "payload": { "$ref": "#/components/schemas/Company/definitions/companyDetails" } } }, "Connection": { "title": "Connection", "description": "A connection represents a [company's](https://docs.codat.io/platform-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/DateTime", "nullable": true }, "created": { "$ref": "#/components/schemas/DateTime" }, "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/DateTime" }, "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/DateTime" } } }, "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" } }, "ConnectionManagementAccessToken": { "title": "Access token", "type": "object", "properties": { "accessToken": { "type": "string", "nullable": false, "description": "Access token that allows SMBs to manage connections that have access to their data.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" } } }, "ConnectionManagementAllowedOrigins": { "title": "Allowed origins", "type": "object", "properties": { "allowedOrigins": { "type": "array", "description": "An array of allowed origins (i.e. your domains) to permit cross-origin resource sharing ([CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)).n resource sharing ([CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)).", "items": { "type": "string", "format": "uri", "description": "A domain you want to allow CORS with Codat." } } }, "example": { "allowedOrigins": [ "https://www.bank-of-dave.com" ] } }, "Connections": { "title": "Connections", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "ConnectionStatusChangedWebhook": { "title": "Connection status changed webhook", "x-internal": true, "description": "Webhook request body for a company's data connection status changed.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientId" }, "ClientName": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/ClientName" }, "CompanyId": { "$ref": "#/components/parameters/companyId/schema" }, "DataConnectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "RuleId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/Message" }, "Data": { "$ref": "#/components/schemas/ConnectionStatusChangedWebhook/definitions/ConnectionStatusChangedWebhookData" } }, "definitions": { "ConnectionStatusChangedWebhookData": { "type": "object", "title": "Connection status changed webhook data", "properties": { "dataConnectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "newStatus": { "description": "The new authorization status of the data connection.", "$ref": "#/components/schemas/Connection/definitions/dataConnectionStatus" }, "oldStatus": { "description": "The old authorization status of the data connection.", "$ref": "#/components/schemas/Connection/definitions/dataConnectionStatus" }, "platformKey": { "$ref": "#/components/parameters/platformKey/schema" } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002", "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "DataConnectionStatusChanged", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "Data connection for SandBox status changed from PendingAuth to Linked", "Data": { "dataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "newStatus": "Linked", "oldStatus": "PendingAuth", "platformKey": "gbol" } } ] }, "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/DateTime", "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" } } } } }, "CreateApiKey": { "title": "Create API key", "description": "Details about the newly created API key.", "x-internal": true, "type": "object", "properties": { "name": { "$ref": "#/components/schemas/ApiKeyDetails/allOf/0/properties/name" } } }, "CustomDataTypeConfiguration": { "title": "Custom data type configuration", "type": "object", "description": "Client's configuration details for a specific custom data type and platform pair.", "properties": { "dataSource": { "type": "string", "description": "Underlying endpoint of the source platform that will serve as a data source for the custom data type. This value is not validated by Codat." }, "requiredData": { "type": "object", "description": "Properties required to be fetched from the underlying platform for the custom data type that is being configured. This value is not validated by Codat.", "additionalProperties": { "type": "string", "description": "The client's defined name for the property with the value being the source system's property name which the mapping is targeting." } }, "keyBy": { "type": "array", "description": "An array of properties from the source system that can be used to uniquely identify the records returned for the custom data type. This value is not validated by Codat.", "items": { "type": "string" }, "minLength": 1 }, "sourceModifiedDate": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Property in the source platform nominated by the client that defines the date when a record was last modified there. This value is not validated by Codat." } }, "examples": [ { "dataSource": "api/purchaseOrders?$filter=currencyCode eq 'NOK'", "requiredData": { "currencyCode": "$[*].currencyCode", "id": "$[*].id", "number": "$[*].number", "orderDate": "$[*].orderDate", "totalAmountExcludingTax": "$[*].totalAmountExcludingTax", "totalTaxAmount": "$[*].totalTaxAmount", "vendorName": "$[*].number" }, "keyBy": [ "$[*].id" ], "sourceModifiedDate": [ "$[*].lastModifiedDateTime" ] } ] }, "CustomDataTypeRecords": { "title": "Custom data type records", "type": "object", "description": "Resulting records pulled from the source platform for a specific custom data type.", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CustomDataTypeRecords/definitions/customDataTypeRecord" } }, "pageNumber": { "$ref": "#/components/schemas/PagingInfo/properties/pageNumber" }, "pageSize": { "$ref": "#/components/schemas/PagingInfo/properties/pageSize" }, "totalResults": { "$ref": "#/components/schemas/PagingInfo/properties/totalResults" } }, "definitions": { "customDataTypeRecord": { "title": "Custom data type record", "type": "object", "properties": { "id": { "type": "string", "nullable": false, "description": "Unique identifier of the record." }, "content": { "type": "object", "description": "Values from the source system for the properties defined in the custom data type configuration.", "additionalProperties": { "type": "object" } }, "modifiedDate": { "title": "ModifiedDate", "x-internal": true, "type": "object", "properties": { "modifiedDate": { "allOf": [ { "$ref": "#/components/schemas/DateTime" }, { "description": "The date when the record was last fetched from the data source and updated in Codat’s data cache. \n\nUse it to identify and retrieve records that have changed since your last fetch. For example, filtering `modifiedDate` to today will provide new records updated in Codat today.\n\nThis date is populated for all data types except for attachments, balance sheets, company information, and profit & loss reports ([read more](https://docs.codat.io/using-the-api/modified-dates#modified-date)).\n\nIn Codat's data model, dates and times are represented using the ISO 8601 standard." } ] } } } } } } }, "DatasetDataChangedWebhook": { "title": "Dataset data changed webhook", "x-internal": true, "description": "Webhook request body to notify that a data synchronization has completed.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientId" }, "ClientName": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/ClientName" }, "CompanyId": { "$ref": "#/components/parameters/companyId/schema" }, "DataConnectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "RuleId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/Message" }, "Data": { "title": "Dataset data changed webhook data", "type": "object", "properties": { "dataType": { "$ref": "#/components/schemas/DataStatus/properties/dataType" }, "datasetId": { "$ref": "#/components/parameters/datasetId/schema" } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002", "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Dataset data changed", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "Data has changed for dataset type invoices, company 8a210b68-6988-11ed-a1eb-0242ac120002", "Data": { "dataType": "invoices", "datasetId": "6586f21b-ad4d-4d06-a309-712af47184a2" } } ] }, "DatasetStatusChangedErrorWebhook": { "title": "Dataset status changed to error webhook", "x-internal": true, "description": "Webhook request body to notify that a data synchronization has completed.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientId" }, "ClientName": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/ClientName" }, "CompanyId": { "$ref": "#/components/parameters/companyId/schema" }, "DataConnectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "RuleId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/Message" }, "Data": { "$ref": "#/components/schemas/DatasetStatusChangedErrorWebhook/definitions/DatasetStatusChangedErrorWebhookData" } }, "definitions": { "DatasetStatusChangedErrorWebhookData": { "type": "object", "title": "Dataset status changed to error webhook data", "properties": { "dataType": { "$ref": "#/components/schemas/DataStatus/properties/dataType" }, "datasetStatus": { "type": "string", "description": "The current status of the dataset's sync." }, "datasetId": { "$ref": "#/components/parameters/datasetId/schema" } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002", "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Data Sync Status Changed To Error", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "ERROR: syncing payments triggered a ProcessingError notification at 2020-04-21T12:12:57.4250446Z.", "Data": { "dataType": "invoices", "datasetStatus": "ProcessingError", "datasetId": "6586f21b-ad4d-4d06-a309-712af47184a2" } } ] }, "DataStatus": { "title": "Data status", "description": "Describes the state of data in the Codat cache for a company and data type", "type": "object", "required": [ "dataType", "lastSuccessfulSync", "currentStatus" ], "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" }, "lastSuccessfulSync": { "$ref": "#/components/schemas/DateTime" }, "currentStatus": { "$ref": "#/components/schemas/PullOperation/properties/status" }, "latestSyncId": { "type": "string", "description": "Unique identifier for most recent sync of data type.", "format": "uuid", "example": "ad474a37-2003-478e-baee-9af9f1ec2fe3" }, "latestSuccessfulSyncId": { "type": "string", "description": "Unique identifier for the most recent successful sync of data type.", "format": "uuid", "example": "8220fc90-55b6-47bc-9417-48ac6ea93101" } }, "examples": [ { "dataType": "string", "lastSuccessfulSync": "2022-01-01T13:00:00.000Z", "currentStatus": "string", "latestSyncId": "ad474a37-2003-478e-baee-9af9f1ec2fe3", "latestSuccessfulSyncId": "8220fc90-55b6-47bc-9417-48ac6ea93101" } ] }, "DataStatuses": { "title": "Data statuses", "x-internal": true, "type": "object", "properties": { "accountTransactions": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "balanceSheet": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "bankAccounts": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "bankTransactions": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "billCreditNotes": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "billPayments": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "bills": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "cashFlowStatement": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "chartOfAccounts": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "company": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "creditNotes": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "customers": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "directCosts": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "directIncomes": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "invoices": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "itemReceipts": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "items": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "journalEntries": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "journals": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "paymentMethods": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "payments": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "profitAndLoss": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "purchaseOrders": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "salesOrders": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "suppliers": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "taxRates": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "trackingCategories": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "transfers": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "banking-accountBalances": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "banking-accounts": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "banking-transactionCategories": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "banking-transactions": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-companyInfo": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-customers": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-disputes": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-locations": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-orders": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-paymentMethods": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-payments": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-productCategories": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-products": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-taxComponents": { "$ref": "#/components/schemas/DataStatus", "nullable": true }, "commerce-transactions": { "$ref": "#/components/schemas/DataStatus", "nullable": true } } }, "DataSyncCompletedWebhook": { "title": "Data sync completed webhook", "x-internal": true, "description": "Webhook request body to notify the completion of a data sync.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientId" }, "ClientName": { "type": "string", "description": "Name of your client in Codat." }, "CompanyId": { "$ref": "#/components/parameters/companyId/schema" }, "DataConnectionId": { "$ref": "#/components/parameters/connectionId/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." }, "Data": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/definitions/DataSyncCompletedWebhookData" } }, "definitions": { "DataSyncCompletedWebhookData": { "type": "object", "title": "Data sync completed webhook data", "properties": { "dataType": { "$ref": "#/components/schemas/DataStatus/properties/dataType", "nullable": true }, "datasetId": { "$ref": "#/components/parameters/datasetId/schema" } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002", "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Data sync completed", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "Data sync of type creditNotes completed for company 7626befb-0c7d-49a4-9366-bc4c81b4e4b7", "Data": { "dataType": "creditNotes", "datasetId": "1541a5ee-0d84-4b6e-a7f7-c07c1f216333" } } ] }, "DataType": { "x-internal": true, "$ref": "#/components/schemas/DataStatus/properties/dataType" }, "DataTypeWriteWebhook": { "title": "Write data type 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": [ "bills.write.successful", "bills.write.unsuccessful" ] }, "generatedDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC the event was generated in Codat." }, "payload": { "$ref": "#/components/schemas/DataTypeWriteWebhook/definitions/dataTypeWriteWebhookPayload" } }, "definitions": { "dataTypeWriteWebhookPayload": { "title": "Payload", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the write request. This is also known as the push operation ID." }, "type": { "$ref": "#/components/schemas/DataTypeWriteWebhook/definitions/writeType" }, "referenceCompany": { "$ref": "#/components/schemas/Company/definitions/companyReference" }, "connectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "requestedOnDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC the write request was submitted." }, "completedOnDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC the write request completed." }, "status": { "$ref": "#/components/schemas/DataTypeWriteWebhook/definitions/writeStatus" }, "record": { "$ref": "#/components/schemas/DataTypeWriteWebhook/definitions/dataTypeWriteWebhookRecord", "nullable": true }, "attachmentId": { "type": "string", "nullable": true, "description": "Unique identifier for the uploaded attachment, null if no attachment uploaded." } } }, "dataTypeWriteWebhookRecord": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the data type created, updated, deleted, or had an attachment uploaded in the accounting platform." } } }, "writeType": { "title": "Write type", "description": "Type of write request.", "type": "string", "enum": [ "Create", "Update", "Delete", "UploadAttachment" ] }, "writeStatus": { "title": "Write request status", "type": "string", "enum": [ "Pending", "Failed", "Success", "TimedOut" ], "description": "The current status of the write request, which is the same as the push operation status." } } }, "DateTime": { "title": "Date time", "type": "string", "examples": [ "2022-10-23T00:00:00.000Z", "2022-10-23T00:00:00.000Z" ], "description": "In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example:\n\n```\n2020-10-08T22:40:50Z\n2021-01-01T00:00:00\n```\n\n\n\nWhen syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:\n\n- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`\n- Unqualified local time: `2021-11-15T01:00:00`\n- UTC time offsets: `2021-11-15T01:00:00-05:00`\n\n> Time zones\n> \n> Not all dates from Codat will contain information about time zones. \n> Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced." }, "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": { "$ref": "#/components/schemas/DataStatus/properties/dataType" }, "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" } ] }, "NewCompanySynchronizedWebhook": { "title": "New company synchronized webhook", "x-internal": true, "description": "Webhook request body to notify that a new company has successfully synchronized at least one dataType for the first time.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientId" }, "ClientName": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/ClientName" }, "CompanyId": { "$ref": "#/components/parameters/companyId/schema" }, "DataConnectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "RuleId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/Message" } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002", "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "New company synchronised", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "Company 8a210b68-6988-11ed-a1eb-0242ac120002 synced for the first time" } ] }, "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" } } } ] }, "Profile": { "title": "Profile", "description": "Describes your Codat client instance", "examples": [ { "name": "Bob's Burgers", "logoUrl": "https://client-images.codat.io/logo/042399f5-d104-4f38-9ce8-cac3524f4e88_5806cb1f-7342-4c0e-a0a8-99bfbc47b0ff.png", "iconUrl": "https://client-images.codat.io/icon/042399f5-d104-4f38-9ce8-cac3524f4e88_3f5623af-d992-4c22-bc08-e58c520a8526.ico", "redirectUrl": "https://bobs-burgers.{countrySuffix}/{companyId}", "whiteListUrls": [ "https://bobs-burgers.com", "https://bobs-burgers.co.uk" ], "confirmCompanyName": true } ], "type": "object", "properties": { "name": { "type": "string", "example": "Bob's Burgers", "description": "The name given to the instance." }, "logoUrl": { "type": "string", "description": "Static url to your organization's logo.", "example": "https://client-images.codat.io/logo/042399f5-d104-4f38-9ce8-cac3524f4e88_5806cb1f-7342-4c0e-a0a8-99bfbc47b0ff.png" }, "iconUrl": { "type": "string", "description": "Static url to your organization's icon.", "example": "https://client-images.codat.io/icon/042399f5-d104-4f38-9ce8-cac3524f4e88_3f5623af-d992-4c22-bc08-e58c520a8526.ico" }, "redirectUrl": { "type": "string", "example": "https://bobs-burgers.{countrySuffix}/{companyId}", "description": "The redirect URL pasted on to the SMB once Codat's [Hosted Link](https://docs.codat.io/auth-flow/authorize-hosted-link) has been completed by the SMB." }, "whiteListUrls": { "type": "array", "description": "A list of urls that are allowed to communicate with Codat. If empty any url is allowed to communicate with Codat.", "items": { "type": "string", "format": "uri", "example": "https://bobs-burgers.com", "description": "A url that is allowed to communicate with Codat." } }, "apiKey": { "type": "string", "deprecated": true, "example": "sartANTjHAkLdbyDfaynoTQb7pkmj6hXHmnQKMrB", "description": "The API key for this Codat instance." }, "alertAuthHeader": { "type": "string", "example": "Bearer tXEiHiRK7XCtI8TNHbpGs1LI1pumdb4Cl1QIo7B2", "description": "Alert or webhooks authorization header." }, "confirmCompanyName": { "type": "boolean", "deprecated": true, "description": "`True` if the company name has been confirmed." } }, "required": [ "name", "redirectUrl" ], "x-stoplight": { "id": "b1fyq05edangf" } }, "PullOperation": { "title": "Pull operation", "description": "Information about a queued, in progress or completed pull operation.\n*Formally called `dataset`*", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the pull operation.", "example": "943accd0-4247-42d8-865b-363c8629e1da" }, "companyId": { "type": "string", "format": "uuid", "description": "Unique identifier of the company associated to this pull operation.", "example": "22ece347-e5f6-4896-95e0-35a4c7f17023" }, "connectionId": { "type": "string", "format": "uuid", "description": "Unique identifier of the connection associated to this pull operation.", "example": "50830828-7d39-4367-b0eb-5ddb2de5faa5" }, "dataType": { "title": "Data types", "x-internal": true, "type": "string", "description": "The data type you are requesting in a pull operation." }, "status": { "title": "Dataset status", "type": "string", "description": "The current status of the dataset.", "enum": [ "Initial", "Queued", "Fetching", "MapQueued", "Mapping", "Complete", "FetchError", "MapError", "InternalError", "ProcessingQueued", "Processing", "ProcessingError", "ValidationQueued", "Validating", "ValidationError", "AuthError", "Cancelled", "NotSupported", "RateLimitError", "PermissionsError", "PrerequisiteNotMet" ] }, "statusDescription": { "type": "string", "nullable": true, "description": "Additional information about the dataset status.", "example": "Paused until 2022-10-23T00:00:00.000Z" }, "errorMessage": { "type": "string", "nullable": true, "description": "A message about a transient or persistent error returned by Codat or the source platform." }, "requested": { "$ref": "#/components/schemas/DateTime" }, "completed": { "$ref": "#/components/schemas/DateTime" }, "progress": { "type": "integer", "description": "An integer signifying the progress of the pull operation." }, "isCompleted": { "type": "boolean", "description": "`True` if the pull operation is completed successfully. The `isCompleted` property is not queryable. To filter failed pull operations, query by `status!=Complete&&status!=NotSupported` instead." }, "isErrored": { "type": "boolean", "description": "`True` if the pull operation entered an error state." } }, "required": [ "id", "companyId", "connectionId", "dataType", "status", "requested", "progress", "isCompleted", "isErrored" ], "examples": [ { "id": "97d60846-f07a-4d42-b5a0-0bdcc6ebf56b", "companyId": "4645bd78-8988-45bc-ac9e-67ba5df6e4e5", "connectionId": "51baa045-4836-4317-a42e-3542e991e581", "dataType": "invoices", "status": "Initial", "statusDescription": "Paused until 2022-10-23T00:00:00.000Z", "requested": "2022-11-14T11:18:37.2798351Z", "progress": 10, "isCompleted": false, "isErrored": false } ] }, "PullOperations": { "title": "Pull operations", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PullOperation" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "PushOperation": { "title": "Push operation", "type": "object", "x-internal": true, "properties": { "changes": { "type": "array", "nullable": true, "description": "Contains a single entry that communicates which record has changed and the manner in which it changed. ", "items": { "$ref": "#/components/schemas/PushOperation/definitions/pushOperationChange" } }, "dataType": { "$ref": "#/components/schemas/DataStatus/properties/dataType", "description": "The type of data being pushed, eg invoices, customers." }, "companyId": { "$ref": "#/components/parameters/companyId/schema" }, "pushOperationKey": { "type": "string", "format": "uuid", "description": "A unique identifier generated by Codat to represent this single push operation. This identifier can be used to track the status of the push, and should be persisted." }, "dataConnectionKey": { "$ref": "#/components/parameters/connectionId/schema" }, "requestedOnUtc": { "$ref": "#/components/schemas/DateTime", "description": "The datetime when the push was requested." }, "completedOnUtc": { "$ref": "#/components/schemas/DateTime", "description": "The datetime when the push was completed, null if Pending." }, "timeoutInMinutes": { "type": "integer", "format": "int32", "nullable": true, "description": "Number of minutes the push operation must complete within before it times out." }, "timeoutInSeconds": { "type": "integer", "format": "int32", "nullable": true, "deprecated": true, "description": "Number of seconds the push operation must complete within before it times out." }, "status": { "$ref": "#/components/schemas/PushOperation/definitions/pushOperationStatus" }, "errorMessage": { "type": "string", "nullable": true, "description": "A message about the error." }, "validation": { "$ref": "#/components/schemas/PushOperation/definitions/validation" }, "statusCode": { "type": "integer", "description": "Push status code." } }, "required": [ "companyId", "pushOperationKey", "dataConnectionKey", "requestedOnUtc", "status", "statusCode" ], "definitions": { "validation": { "type": "object", "title": "Validation", "description": "A human-readable object describing validation decisions Codat has made when pushing data into the platform. If a push has failed because of validation errors, they will be detailed here.", "properties": { "errors": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PushOperation/definitions/validationItem" } }, "warnings": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PushOperation/definitions/validationItem" } } } }, "validationItem": { "title": "Validation 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." } }, "additionalProperties": false }, "pushChangeType": { "title": "Push change type", "description": "Type of change being applied to record in third party platform.", "type": "string", "enum": [ "Unknown", "Created", "Modified", "Deleted", "AttachmentUploaded" ] }, "pushOperationRef": { "title": "Push operation reference", "x-internal": true, "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for a push operation." }, "dataType": { "$ref": "#/components/schemas/DataStatus/properties/dataType", "nullable": true } }, "additionalProperties": false }, "pushOperationStatus": { "title": "Push operation status", "type": "string", "enum": [ "Pending", "Failed", "Success", "TimedOut" ], "description": "The current status of the push operation." }, "pushOperationChange": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PushOperation/definitions/pushChangeType" }, "recordRef": { "$ref": "#/components/schemas/PushOperation/definitions/pushOperationRef" }, "attachmentId": { "type": "string", "description": "Unique identifier for the attachment created otherwise null.", "nullable": true } } } } }, "PushOperations": { "title": "Push operations", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PushOperation" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "PushOperationStatusChangedWebhook": { "title": "Push operation status changed webhook", "x-internal": true, "description": "Webhook request body for a push operation status change.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientId" }, "ClientName": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/ClientName" }, "CompanyId": { "$ref": "#/components/parameters/companyId/schema" }, "DataConnectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "RuleId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/Message" }, "Data": { "$ref": "#/components/schemas/PushOperationStatusChangedWebhook/definitions/PushOperationStatusChangedWebhookData" } }, "definitions": { "PushOperationStatusChangedWebhookData": { "type": "object", "title": "Push operation status changed webhook data", "properties": { "dataType": { "$ref": "#/components/schemas/DataStatus/properties/dataType" }, "status": { "$ref": "#/components/schemas/PushOperation/definitions/pushOperationStatus" }, "pushOperationKey": { "$ref": "#/components/schemas/PushOperation/properties/pushOperationKey" } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002", "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Push Operation Status Changed()", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "invoices triggered notification for PushOperationStatusChanged at 2019-05-22T18:19:42.742Z", "Data": { "dataType": "invoices", "status": "Success", "pushOperationKey": "c2f8847d-3047-4619-a157-6d947d8e4a73" } } ] }, "PushOperationTimedOutWebhook": { "title": "Push operation timed out webhook", "x-internal": true, "description": "Webhook request body notifying that a push push operation has timed out.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientId" }, "ClientName": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/ClientName" }, "CompanyId": { "$ref": "#/components/parameters/companyId/schema" }, "DataConnectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "RuleId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/DataSyncCompletedWebhook/properties/Message" }, "Data": { "$ref": "#/components/schemas/PushOperationTimedOutWebhook/definitions/PushOperationTimedOutWebhookData" } }, "definitions": { "PushOperationTimedOutWebhookData": { "type": "object", "title": "Push operation timed out webhook data", "properties": { "dataType": { "$ref": "#/components/schemas/DataStatus/properties/dataType" }, "pushOperationKey": { "$ref": "#/components/schemas/PushOperation/properties/pushOperationKey" }, "pushOperationGuid": { "$ref": "#/components/schemas/PushOperation/properties/pushOperationKey", "deprecated": true, "x-speakeasy-deprecation-replacement": "pushOperationKey" } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002", "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Push Operation Timed Out", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "ERROR: pushing invoices never finished in time, timing out at 2020-09-07T08:42:13", "Data": { "dataType": "invoices", "pushOperationKey": "c2f8847d-3047-4619-a157-6d947d8e4a73", "pushOperationGuid": "c2f8847d-3047-4619-a157-6d947d8e4a73" } } ] }, "PushOption": { "title": "Push option", "x-internal": true, "required": [ "displayName", "required", "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionType" }, "displayName": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/displayName" }, "description": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/description" }, "required": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/required" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty" }, "nullable": true }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionChoice" }, "nullable": true }, "validation": { "$ref": "#/components/schemas/PushOption/definitions/pushValidationInfo", "nullable": true } }, "definitions": { "pushOptionProperty": { "title": "Push Option Property", "required": [ "description", "displayName", "required", "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionType" }, "displayName": { "minLength": 1, "type": "string", "description": "The property's display name." }, "description": { "type": "string", "description": "A description of the property." }, "required": { "type": "boolean", "description": "The property is required if `True`." }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty" }, "nullable": true }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionChoice" }, "nullable": true }, "validation": { "$ref": "#/components/schemas/PushOption/definitions/pushValidationInfo" } } }, "pushValidationInfo": { "title": "Push validation info", "type": "object", "properties": { "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PushOption/definitions/pushFieldValidation" }, "nullable": true }, "information": { "type": "array", "items": { "$ref": "#/components/schemas/PushOption/definitions/pushFieldValidation" }, "nullable": true } }, "additionalProperties": false }, "pushFieldValidation": { "title": "Push field validation", "required": [ "details" ], "type": "object", "properties": { "field": { "type": "string", "description": "Field name that resulted in the validation issue." }, "details": { "minLength": 1, "type": "string", "description": "Details on the validation issue." }, "ref": { "type": "string", "format": "uri", "nullable": true, "description": "Unique reference identifier for the validation issue." } }, "additionalProperties": false }, "pushOptionType": { "title": "Option Type", "description": "The option type.", "enum": [ "Array", "Object", "String", "Number", "Boolean", "DateTime", "File", "MultiPart" ], "type": "string" }, "pushOptionChoice": { "title": "Push Option Choice", "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Allowed value for field." }, "type": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionType" }, "displayName": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/displayName" }, "description": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/description" }, "required": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/required" } } } } }, "ReadCompletedWebhook": { "title": "Read completed webhook", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "description": "Unique identifier of the event." }, "eventType": { "type": "string", "description": "The type of event." }, "generatedDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC the event was generated in Codat." }, "payload": { "$ref": "#/components/schemas/ReadCompletedWebhook/definitions/readCompletedWebhookPayload" } }, "definitions": { "readCompletedWebhookPayload": { "title": "Company fetch completed webhook payload", "type": "object", "properties": { "referenceCompany": { "$ref": "#/components/schemas/Company/definitions/companyReference" }, "modifiedFromDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC when the data types were last fetched and input into Codat's cache.", "nullable": true }, "dataTypes": { "type": "array", "items": { "type": "object", "properties": { "connectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "dataType": { "$ref": "#/components/schemas/DataStatus/properties/dataType" }, "recordsModified": { "type": "boolean", "example": false, "description": "`True` if records have been created, updated or deleted in Codat's cache." }, "status": { "$ref": "#/components/schemas/PullOperation/properties/status" } } } } } } } }, "SupplementalDataConfiguration": { "description": "", "title": "Supplemental data configuration", "type": "object", "properties": { "supplementalDataConfig": { "type": "object", "additionalProperties": { "type": "object", "title": "Supplemental data source configuration", "description": "The client's defined name for the object.", "properties": { "dataSource": { "type": "string", "description": "The underlying endpoint of the source system which the configuration is targeting. " }, "pullData": { "type": "object", "description": "The additional properties that are required when pulling records.", "additionalProperties": { "type": "string", "description": "The client's defined name for the property with the value being the source system's property name which the mapping is targeting." } }, "pushData": { "type": "object", "description": "The additional properties that are required to create and/or update records.", "additionalProperties": { "type": "string", "description": "The client's defined name for the property with the value being the source system's property name which the mapping is targeting." } } } } } }, "examples": [ { "supplementalDataConfig": { "orders-supplemental-data": { "dataSource": "/orders", "pullData": { "orderNumber": "order_num" }, "pushData": { "orderNumber": "order_num" } } } } ] }, "SyncSetting": { "title": "SyncSetting", "description": "Describes how often, and how much history, should be fetched for the given data type when a pull operation is queued.", "examples": [ { "dataType": "invoices", "fetchOnFirstLink": true, "syncSchedule": 24, "syncOrder": 0, "syncFromUtc": "2020-01-01T12:00:00.000Z", "syncFromWindow": 24, "monthsToSync": 24, "isLocked": true } ], "type": "object", "properties": { "dataType": { "$ref": "#/components/schemas/DataStatus/properties/dataType" }, "fetchOnFirstLink": { "type": "boolean", "description": "Whether this data type should be queued after a company has authorized a connection." }, "syncSchedule": { "type": "integer", "example": 24, "description": "Number of hours after which this data type should be refreshed." }, "syncOrder": { "type": "integer", "description": "The sync in which data types are queued for a sync." }, "syncFromUtc": { "$ref": "#/components/schemas/DateTime", "description": "Date from which data should be fetched. Set this *or* `syncFromWindow`." }, "syncFromWindow": { "type": "integer", "example": 24, "description": "Number of months of data to be fetched. Set this *or* `syncFromUTC`." }, "monthsToSync": { "type": "integer", "example": 24, "description": "Months of data to fetch, for report data types (`balanceSheet` & `profitAndLoss`) only." }, "isLocked": { "type": "boolean", "description": "`True` if the [sync setting](https://docs.codat.io/knowledge-base/advanced-sync-settings) is locked." } }, "required": [ "dataType", "fetchOnFirstLink", "syncSchedule", "syncOrder" ] }, "SyncSettings": { "title": "Sync settings", "x-internal": true, "type": "object", "properties": { "clientId": { "$ref": "#/components/schemas/ClientId" }, "settings": { "type": "array", "items": { "$ref": "#/components/schemas/SyncSetting" } }, "overridesDefaults": { "type": "boolean", "description": "Set to `True` if you want to override the default [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings)." } } }, "UpdateConnectionStatus": { "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 }, "Webhook": { "title": "Webhook", "description": "Configuration to provide an event notification to a URL or list of email addresses based on the given type or condition.", "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "nullable": false, "description": "Unique identifier for the configured notification.", "example": "ff89c50e-a719-4ef5-a182-9917e53927b6" } } }, { "$ref": "#/components/schemas/Webhook/definitions/createRule" } ], "definitions": { "createRule": { "title": "Create webhook", "description": "Create a message that notifies a URL of an event based on its given type or condition.", "type": "object", "properties": { "type": { "type": "string", "description": "The type of webhook." }, "companyId": { "$ref": "#/components/parameters/companyId/schema" }, "notifiers": { "$ref": "#/components/schemas/Webhook/definitions/webhookNotifier" } }, "examples": [ { "type": "DataConnectionStatusChanged", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } ], "required": [ "type", "notifiers" ] }, "webhookNotifier": { "type": "object", "title": "Webhook notifiers", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email", "description": "Receiver's email address.", "example": "info@client.com" } }, "webhook": { "type": "string", "format": "uri", "description": "The URI the webhook service will use to post events.", "example": "https://webhook.client.com" } } }, "webhooks": { "title": "Webhooks", "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] } }, "examples": [ { "id": "ff89c50e-a719-4ef5-a182-9917e53927b6", "type": "DataConnectionStatusChanged", "companyId": "39b73b17-cc2e-429e-915d-71654e9dcd1e", "notifiers": { "emails": [ "info@client.com" ], "webhook": "https://webhook.client.com" } } ] }, "WebhookConsumer": { "title": "Webhook consumer", "type": "object", "description": "A webhook consumer is an HTTP endpoint that developers can configure to subscribe to Codat's supported event types.\n\nSee our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview).\n", "properties": { "id": { "type": "string", "format": "uuid", "example": "8a210b68-6988-11ed-a1eb-0242ac120002", "description": "Unique identifier for the webhook consumer." }, "url": { "type": "string", "format": "uri", "description": "The URL that will consume webhook events dispatched by Codat." }, "disabled": { "type": "boolean", "description": "Flag that enables or disables the endpoint from receiving events. Disabled when set to `true`.", "nullable": true, "default": false }, "eventTypes": { "type": "array", "description": "An array of event types the webhook consumer subscribes to.", "items": { "type": "string" } }, "companyTags": { "type": "array", "description": "Company tags provide an additional way to filter messages, independent of event types. Company tags are case-sensitive, and only messages from companies with matching tags will be sent to this endpoint. Use the format `tagKey:tagValue`.", "items": { "type": "string", "maxLength": 128 }, "maxItems": 10 }, "companyId": { "deprecated": true, "type": "string", "format": "uuid", "nullable": true, "example": "8a210b68-6988-11ed-a1eb-0242ac120002", "description": "Unique identifier of the company to indicate company-specific events. The associated webhook consumer will receive events only for the specified ID." } }, "definitions": { "webhookConsumerPrototype": { "title": "Create webhook consumer", "type": "object", "properties": { "url": { "$ref": "#/components/schemas/WebhookConsumer/properties/url" }, "disabled": { "$ref": "#/components/schemas/WebhookConsumer/properties/disabled" }, "eventTypes": { "$ref": "#/components/schemas/WebhookConsumer/properties/eventTypes" }, "companyTags": { "$ref": "#/components/schemas/WebhookConsumer/properties/companyTags" }, "companyId": { "$ref": "#/components/schemas/WebhookConsumer/properties/companyId" } } }, "webhookConsumers": { "title": "Webhook consumers", "type": "object", "properties": { "results": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/WebhookConsumer" } } } } } }, "WebhookZapierKey": { "title": "Zapier integration key", "type": "object", "properties": { "key": { "type": "string", "description": "Integration key used to authorize Zapier's HTTP requests with Codat.", "example": "sk_integ_WM4dfoK1nKZnDE_kceze6hWDjbRwOZwG.us" } }, "examples": [ { "key": "sk_integ_WM4dfoK1nKZnDE_kceze6hWDjbRwOZwG.us" } ] } }, "responses": { "Bad-Request": { "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 } } } } } }, "ConnectionManagementAllowedOrigins": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionManagementAllowedOrigins" }, "examples": { "Allowed origins": { "$ref": "#/components/examples/connectionManagementAllowedOriginsResponse" } } } } }, "Malformed-Query": { "description": "Your `query` parameter was not correctly formed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Malformed query": { "value": { "statusCode": 400, "service": "ClientsApi", "error": "Error parsing query - Malformed query.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } }, "Unresolved property": { "value": { "statusCode": 400, "service": "PullApi", "error": "Error parsing query - Could not resolve property isCompleted on Dataset", "correlationId": "98457fb9956b7f9b4b2fd4f6e23bb5c8", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Unauthorized": { "description": "Your API request was not properly authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Unauthorized": { "value": { "statusCode": 401, "service": "PublicApi", "error": "Unauthorized", "correlationId": "7eb40d6b415d7bcd99ce658268284056", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Payment-Required": { "description": "An account limit has been exceeded. The type of limit is described in the error property:\n\n- You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request.\n- The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan.\n- Your Free account is older than 365 days and has expired. Contact support@codat.io.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 429, "service": "PublicApi", "error": "You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Forbidden": { "description": "You are using an outdated API key or a key not associated with that resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 403, "service": "PublicApi", "error": "You are using an outdated API key or a key not associated with that resource.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Not-Found": { "description": "One or more of the resources you referenced could not be found.\nThis might be because your company or data connection id is wrong, or was already deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Data connection not found": { "value": { "statusCode": 404, "service": "PublicApi", "error": "Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found", "correlationId": "8fa2b5f4794970a4ee73758f612e8df0", "canBeRetried": "Unknown", "detailedErrorCode": 0 } }, "Company not found": { "value": { "statusCode": 404, "service": "ClientsApi", "error": "No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e", "correlationId": "0a40c2f31fc8f992fb88b0853e4166f3", "canBeRetried": "Unknown", "detailedErrorCode": 0 } }, "No data available": { "value": { "statusCode": 404, "service": "PublicApi", "error": "No data available for accounts for ID e5889b459f544926ac5b8e6756df2s", "correlationId": "0a40c2f31fc8f992fb88b0853e4166f3", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "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 } } } } } }, "Legal-Reasons": { "description": "Not currently available due to compliance limitations. Reach out to your Codat contact for further assistance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 451, "service": "StdznCustomData", "error": "Platform 'qudb' is not currently available for compliance purposes.", "correlationId": "f63017dabb9b87865573bea95a51e55d", "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": { "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." }, "customDataIdentifier": { "name": "customDataIdentifier", "in": "path", "required": true, "schema": { "type": "string", "example": "DynamicsPurchaseOrders" }, "description": "Unique identifier for a custom data type." }, "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)." }, "productIdentifier": { "name": "productIdentifier", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "bank-feeds", "lending", "payables", "expenses" ] }, "description": "Human-readable product identifier for a product." }, "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)." }, "dataType": { "name": "dataType", "description": "The key of a Codat data type.", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DataType" } }, "ruleId": { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7318949f-c008-4936-a8ff-10d7ab563fa6" }, "description": "Unique ID of the webhook or rule." }, "datasetId": { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Unique identifier for the dataset that completed its sync." }, "description": "Unique identifier for the dataset that completed its 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." }, "webhookId": { "name": "webhookId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookConsumer/properties/id" }, "description": "Unique identifier for the webhook consumer." } }, "examples": { "connectionManagementAllowedOriginsResponse": { "value": { "allowedOrigins": [ "https://www.bank-of-dave.com" ] } } }, "securitySchemes": { "auth_header": { "name": "Authorization", "description": "The word \"Basic\" followed by a space and your API key. [API keys](https://docs.codat.io/platform-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)" } } } }