The Codat Platform API provides core functionality used across all Codat solutions, including programmatic creation and management of companies, data connections, and configuration of integrations with accounting, banking, and commerce platforms.
{
"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<!-- Start Codat Tags Table -->\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<!-- End Codat Tags Table -->",
"contact": {
"name": "Codat",
"email": "[email protected]"
},
"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": "Connection management",
"description": "Configure UI and retrieve access tokens for authentication used by **Connections SDK**."
},
{
"name": "Connections",
"description": "Create new and manage existing data connections for a company."
},
{
"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": "Read data",
"description": "View validation outcomes for completed read data 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",
"products": [
"spend-insights",
"lending",
"expenses-v1",
"commerce"
],
"referenceSubsidiaryCompanies": []
}
],
"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",
"products": [
"spend-insights",
"lending",
"payables-v2"
],
"referenceSubsidiaryCompanies": []
},
{
"id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0",
"name": "Toft stores",
"redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0",
"dataConnections": [],
"created": "2022-11-10T10:45:18Z",
"createdByUserName": "Dan Tzabar",
"products": [
"spend-insights"
],
"referenceSubsidiaryCompanies": [
{
"id": "c8d3af58-7011-47ce-b3f2-89faf300ef6d",
"name": "Toft stores UK",
"links": {
"portal": "https://app.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/summary"
}
},
{
"id": "db94eddc-9212-4568-9b5c-3eab0e325913",
"name": "Toft stores US",
"links": {
"portal": "https://app.codat.io/companies/db94eddc-9212-4568-9b5c-3eab0e325913/summary"
}
}
]
},
{
"id": "c8d3af58-7011-47ce-b3f2-89faf300ef6d",
"name": "Toft stores UK",
"redirect": "https://link.codat.io/company/c8d3af58-7011-47ce-b3f2-89faf300ef6d",
"dataConnections": [
{
"id": "d5ab61b7-1ad0-46fd-9f9f-b6761047941e",
"integrationId": "cc750323-5a47-4f28-8d8e-30fbbf2ce137",
"integrationKey": "akxx",
"sourceId": "9815b998-024d-4415-a40b-89903b2cad6f",
"platformName": "Oracle NetSuite",
"linkUrl": "https://link-api.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/connections/d5ab61b7-1ad0-46fd-9f9f-b6761047941e/start",
"status": "Linked",
"lastSync": "2022-01-01T12:30:00.000Z",
"created": "2022-01-01T11:30:00Z",
"sourceType": "Accounting"
}
],
"created": "2022-11-10T10:45:18Z",
"createdByUserName": "Dan Tzabar",
"products": [
"lending",
"spend-insights",
"payables"
],
"referenceParentCompany": {
"id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0",
"name": "Toft stores",
"links": {
"portal": "https://app.codat.io/companies/ab12c58d-a678-4ebf-a159-ae99e1807bd0/summary"
}
},
"referenceSubsidiaryCompanies": []
},
{
"id": "db94eddc-9212-4568-9b5c-3eab0e325913",
"name": "Toft stores US",
"redirect": "https://link.codat.io/company/db94eddc-9212-4568-9b5c-3eab0e325913",
"dataConnections": [
{
"id": "1e5c8c9e-27fd-4ba9-9a2a-d02ba65bc2fb",
"integrationId": "cc750323-5a47-4f28-8d8e-30fbbf2ce137",
"integrationKey": "akxx",
"sourceId": "9815b998-024d-4415-a40b-89903b2cad6f",
"platformName": "Oracle NetSuite",
"linkUrl": "https://link-api.codat.io/companies/db94eddc-9212-4568-9b5c-3eab0e325913/connections/1e5c8c9e-27fd-4ba9-9a2a-d02ba65bc2fb/start",
"status": "Linked",
"lastSync": "2022-01-01T12:30:00.000Z",
"created": "2022-01-01T11:30:00Z",
"sourceType": "Accounting"
}
],
"created": "2022-11-10T10:45:18Z",
"createdByUserName": "Dan Tzabar",
"products": [
"spend-insights"
],
"referenceParentCompany": {
"id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0",
"name": "Toft stores",
"links": {
"portal": "https://app.codat.io/companies/ab12c58d-a678-4ebf-a159-ae99e1807bd0/summary"
}
},
"referenceSubsidiaryCompanies": []
}
],
"pageNumber": 1,
"pageSize": 100,
"totalResults": 3,
"_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](https://docs.codat.io/platform-api#/schemas/Company) 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.\n\n## Filter by tags\n\nThe *List companies* endpoint supports the filtering of companies using [tags](https://docs.codat.io/using-the-api/managing-companies#add-metadata-to-a-company). It supports the following operators with [Codat’s query language](https://docs.codat.io/using-the-api/querying):\n\n- equals (`=`)\n- not equals (`!=`)\n- contains (`~`)\n\nFor example, you can use the querying to filter companies tagged with a specific foreign key, region, or owning team: \n- Foreign key: `uid = {yourCustomerId}`\n- Region: `region != uk`\n- Owning team and region: `region = uk && owningTeam = invoice-finance`",
"parameters": [
{
"$ref": "#/components/parameters/page"
},
{
"$ref": "#/components/parameters/pageSize"
},
{
"$ref": "#/components/parameters/query"
},
{
"$ref": "#/components/parameters/orderBy"
},
{
"name": "tags",
"in": "query",
"schema": {
"type": "string"
},
"example": "region=uk && team=invoice-finance",
"description": "Filter companies by tags using the \"equals\" (=), \"not equals\" (!=), and \"contains\" (~) operators with [Codat’s query language](https://docs.codat.io/using-the-api/querying)."
}
]
},
"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",
"products": [
"spend-insights"
],
"referenceSubsidiaryCompanies": []
}
},
"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",
"products": [
"spend-insights"
],
"referenceSubsidiaryCompanies": []
}
},
"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",
"products": [
"spend-insights"
],
"tags": {
"region": "us"
},
"referenceSubsidiaryCompanies": []
}
}
}
}
}
},
"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": "Toft stores holdings",
"description": "",
"platform": "",
"redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0",
"dataConnections": [],
"created": "2022-11-10T10:45:18Z",
"createdByUserName": "Dan Tzabar",
"products": [
"spend-insights",
"lending",
"expenses-v1",
"commerce"
],
"referenceSubsidiaryCompanies": []
}
},
"Parent multi-entity company": {
"value": {
"id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0",
"name": "Toft stores",
"description": "",
"platform": "",
"redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0",
"dataConnections": [],
"created": "2022-11-10T10:45:18Z",
"createdByUserName": "Dan Tzabar",
"products": [
"spend-insights",
"lending",
"expenses-v1",
"commerce"
],
"referenceSubsidiaryCompanies": [
{
"id": "c8d3af58-7011-47ce-b3f2-89faf300ef6d",
"name": "Toft stores UK",
"links": {
"portal": "https://app.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/summary"
}
},
{
"id": "db94eddc-9212-4568-9b5c-3eab0e325913",
"name": "Toft stores US",
"links": {
"portal": "https://app.codat.io/companies/db94eddc-9212-4568-9b5c-3eab0e325913/summary"
}
}
]
}
},
"Subsidiary multi-entity company": {
"value": {
"id": "c8d3af58-7011-47ce-b3f2-89faf300ef6d",
"name": "Toft stores UK",
"description": "",
"platform": "",
"redirect": "https://link.codat.io/company/c8d3af58-7011-47ce-b3f2-89faf300ef6d",
"dataConnections": [
{
"id": "d5ab61b7-1ad0-46fd-9f9f-b6761047941e",
"integrationId": "cc750323-5a47-4f28-8d8e-30fbbf2ce137",
"integrationKey": "akxx",
"sourceId": "9815b998-024d-4415-a40b-89903b2cad6f",
"platformName": "Oracle NetSuite",
"linkUrl": "https://link-api.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/connections/d5ab61b7-1ad0-46fd-9f9f-b6761047941e/start",
"status": "Linked",
"lastSync": "2022-01-01T12:30:00.000Z",
"created": "2022-01-01T11:30:00Z",
"sourceType": "Accounting"
}
],
"created": "2022-11-10T10:45:18Z",
"createdByUserName": "Dan Tzabar",
"products": [
"spend-insights",
"lending",
"expenses-v1",
"commerce"
],
"referenceParentCompany": {
"id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0",
"name": "Toft stores",
"links": {
"portal": "https://app.codat.io/companies/ab12c58d-a678-4ebf-a159-ae99e1807bd0/summary"
}
},
"referenceSubsidiaryCompanies": []
}
}
}
}
}
},
"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": "Replace company",
"description": "Use the *Replace company* endpoint to replace the existing name, description, and tags of the company. Calling the endpoint will replace existing values even if new values haven't been defined in the payload.\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": "replace-company",
"x-speakeasy-name-override": "replace",
"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"
},
# --- truncated at 32 KB (308 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/codat/refs/heads/main/openapi/codat-platform-openapi.json