{ "openapi": "3.1.0", "servers": [ { "description": "Production", "url": "https://api.codat.io" } ], "info": { "title": "Bill pay kit", "description": "The API reference for the Bill Pay kit. \n\nThe bill pay kit is an API and a set of supporting tools designed to integrate a bill pay flow into your app as quickly as possible. It's ideal for facilitating essential bill payment processes within your SMB's accounting software.\n\n[Explore product](https://docs.codat.io/payables/bill-pay-kit) | [See 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| Company information | View company profile from the source platform. |\n| Bills | Get, create, and update Bills. |\n| Bill payments | Get, create, and update Bill payments. |\n| Suppliers | Get, create, and update Suppliers. |\n| Bank accounts | Create a bank account for a given company's connection. |\n", "version": "3.0.0", "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": "sync-for-payables-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": "Company information", "description": "View company profile from the source platform." }, { "name": "Bills", "description": "Get, create, and update Bills." }, { "name": "Bill payments", "description": "Get, create, and update Bill payments." }, { "name": "Suppliers", "description": "Get, create, and update Suppliers." }, { "name": "Bank accounts", "description": "Create a bank account for a given company's connection." } ], "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/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } }, "description": "Use the *Create company* endpoint to create a new [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) that represents your customer in Codat. \n\nA [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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}": { "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/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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" } } } } } } }, "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/sync-for-payables-api#/schemas/Company), its [connections](https://docs.codat.io/sync-for-payables-api#/schemas/Connection) and any cached data. This operation is irreversible.\n\nA [company](https://docs.codat.io/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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" } } }, "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/sync-for-payables-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/sync-for-payables-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" } } } }, "/companies/{companyId}/connections": { "get": { "summary": "List connections", "description": "List the connections for a company.", "operationId": "list-connections", "tags": [ "Connections" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connections" }, "examples": { "Connections": { "value": { "results": [ { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } ], "pageNumber": 0, "pageSize": 0, "totalResults": 0, "_links": { "self": { "href": "string" }, "current": { "href": "string" }, "next": { "href": "string" }, "previous": { "href": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/Malformed-Query" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "post": { "summary": "Create connection", "description": "Creates a connection for the company by providing a valid `platformKey`. \n\nUse the [List Integrations](https://docs.codat.io/sync-for-payables-api#/operations/list-integrations) endpoint to access valid platform keys. ", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "tags": [ "Connections" ], "operationId": "create-connection", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platformKey": { "type": "string", "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." } } } } } }, "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": { "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 }, "examples": { "Example": { "value": { "status": "Unlinked" } } } } }, "description": "" } } }, "/companies/{companyId}/connections/{connectionId}/payables/info": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "get": { "summary": "Get company information", "description": "Use the *Get company information* endpoint to return information about the company available from the underlying accounting software.\n\n", "operationId": "get-company-information", "tags": [ "Company information" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInformation" }, "examples": { "Company information": { "value": { "companyName": "Bank of Dave", "baseCurrency": "GBP" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/payables/mappingOptions/bills": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "get": { "summary": "Get bill mapping options", "description": "Use the *Get mapping options - Bills* endpoint to return a list of available mapping options for a given company's connection ID.\n\nBy default, this endpoint returns a list of active accounts and tax rates. You can use [querying](https://docs.codat.io/using-the-api/querying) to change that.\n\nMapping options are a set of accounts and tax rates used to configure the SMB's payables integration.", "operationId": "get-mapping-options-bills", "x-speakeasy-name-override": "get-bill-options", "tags": [ "Bills" ], "parameters": [ { "$ref": "#/components/parameters/continuationToken" }, { "$ref": "#/components/parameters/statusQuery" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillMappingOptions" }, "examples": { "Mapping options": { "value": { "accounts": [ { "id": "1b6266d1-1e44-46c5-8eb5-a8f98e03124e", "nominalCode": "879-i", "name": "Accounts payable", "type": "Liability", "currency": "GBP", "status": "Active", "sourceModifiedDate": "2022-10-23T00:00:00.000Z" } ], "taxRates": [ { "id": "d2939064-dd3a-4c0f-9865-a238c2193515", "name": "VAT @ 20%", "code": "VAT20", "effectiveTaxRate": 20, "totalTaxRate": 20, "status": "Active", "sourceModifiedDate": "2022-10-23T00:00:00.000Z" } ], "pagination": { "continuationToken": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/payables/mappingOptions/payments": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "get": { "summary": "Get payment mapping options", "description": "Use the *Get mapping options - Payments* endpoint to return a list of available mapping options for a given company's connection ID.\r\n\r\nBy default, this endpoint returns a list of active bank accounts. You can use [querying](https://docs.codat.io/using-the-api/querying) to change that.\r\n\r\nMapping options are a set of bank accounts used to configure the SMB's payables integration.", "operationId": "get-mapping-options-payments", "x-speakeasy-name-override": "get-payment-options", "tags": [ "Bill payments" ], "parameters": [ { "$ref": "#/components/parameters/continuationToken" }, { "$ref": "#/components/parameters/statusQuery" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMappingOptions" }, "examples": { "Mapping options": { "value": { "bankAccounts": [ { "id": "3d5a8e00-d108-4045-8823-7f342676cffa", "name": "Bank of Dave current account", "accountNumber": "12345678", "currency": "GBP", "nominalCode": "1234567", "sortCode": "123456", "status": "Active", "accountType": "Debit", "sourceModifiedDate": "2022-10-23T00:00:00.000Z" } ], "pagination": { "continuationToken": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/payables/bills": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "get": { "summary": "List bills", "description": "The *List bills* endpoint returns a list of [bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) for a given company's connection.\n\n[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services.\n\nBy default, the endpoint will return all bills with a status of 'Open' & 'PartiallyPaid' to show all oustanding bills.", "operationId": "list-bills", "tags": [ "Bills" ], "parameters": [ { "$ref": "#/components/parameters/continuationToken" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "examples": { "Status (open)": { "value": "status=Open" }, "Status (partially paid)": { "value": "status=PartiallyPaid" }, "Source modified date": { "value": "sourceModifiedDate>2023-12-15T00:00:00.000Z" }, "Status (open) & source modified date": { "value": "sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Open" }, "Status (partially paid) & source modified date": { "value": "sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=PartiallyPaid" } }, "description": "Codat query string allows you to filter by `status` and `sourceModifiedDate`. Learn more about Codat's query string [here](https://docs.codat.io/using-the-api/querying). Platfrom specfic statuses: Xero supports Open | PartiallyPaid | Paid | Void | Draft. Qbo supports Open | PartiallyPaid | Paid. FreeAgent supports Open | PartiallyPaid | Paid." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill/definitions/bills" }, "examples": { "Bills": { "value": { "results": [ { "id": "18", "reference": "12", "supplierRef": { "id": "4", "supplierName": "BILLy elliot" }, "issueDate": "2019-05-13T00:00:00", "dueDate": "2019-05-13T00:00:00", "currency": "GBP", "currencyRate": "1,", "lineItems": [ { "description": "Dance shoes", "unitAmount": 5, "quantity": 1, "taxAmount": 0, "accountRef": { "id": "16" }, "taxRateRef": { "id": "NON" }, "totalAmount": 5 } ], "status": "Open", "totalAmount": 5, "amountDue": 0, "sourceModifiedDate": "2022-05-26T10:34:10Z" }, { "id": "22", "reference": "12", "supplierRef": { "id": "4", "supplierName": "BILLy elliot" }, "issueDate": "2019-05-13T00:00:00", "dueDate": "2019-05-13T00:00:00", "currency": "GBP", "currencyRate": 1, "lineItems": [ { "description": "Dance shoes", "unitAmount": 5, "quantity": 1, "taxAmount": 0, "accountRef": { "id": "16" }, "taxRateRef": { "id": "NON" }, "totalAmount": 5 } ], "status": "Paid", "totalAmount": 5, "amountDue": 0, "sourceModifiedDate": "2022-05-26T10:34:10Z" } ], "pagination": { "continuationToken": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==" } } } } } } }, "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" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "post": { "summary": "Create bill", "description": "The *Create bill* endpoint creates a new [bill](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) for a given company's connection.\n\n[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services.", "operationId": "create-bill", "tags": [ "Bills" ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "description": "A unique identifier to ensure idempotent behaviour for subsequent requests.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill/definitions/billPrototype" }, "examples": { "Create bill": { "value": { "reference": "bill_b8qmmj4ksf1suax", "supplierRef": { "id": "1262c350-fe0f-40ec-aeff-41c95b4a45af", "supplierName": "DIISR - Small Business Services" }, "issueDate": "2023-04-23T00:00:00", "dueDate": "2023-04-23T00:00:00", "currency": "GBP", "currencyRate": 1, "lineItems": [ { "description": "Half day training - Microsoft Office", "unitAmount": 1800, "quantity": 1, "taxAmount": 360, "totalAmount": 2160, "accountRef": { "id": "46f9461e-788b-4906-8b74-d1ea17f6dc10" }, "taxRateRef": { "id": "INPUT2" } }, { "description": "Desktop/network support via email & phone.Per month fixed fee for minimum 20 hours/month.", "unitAmount": 4000, "quantity": 1, "taxAmount": 800, "totalAmount": 4800, "accountRef": { "id": "f96c9458-d724-47bf-8f74-a9d5726465ce" }, "taxRateRef": { "id": "INPUT2" } }, { "description": "Stationery charges", "unitAmount": 32, "quantity": 8, "taxAmount": 51.2, "totalAmount": 307.2, "accountRef": { "id": "cba6527d-f102-4538-b421-e483233e9d5a" }, "taxRateRef": { "id": "INPUT2" } } ], "status": "Open" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill" }, "examples": { "Created bill": { "value": { "id": "bill-1029932", "reference": "bill_b8qmmj4ksf1suax", "supplierRef": { "id": "1262c350-fe0f-40ec-aeff-41c95b4a45af", "supplierName": "DIISR - Small Business Services" }, "issueDate": "2023-04-23T00:00:00", "dueDate": "2023-04-23T00:00:00", "currency": "GBP", "lineItems": [ { "description": "Half day training - Microsoft Office", "unitAmount": 1800, "quantity": 1, "taxAmount": 360, "totalAmount": 2160, "accountRef": { "id": "46f9461e-788b-4906-8b74-d1ea17f6dc10" }, "taxRateRef": { "id": "INPUT2" } }, { "description": "Desktop/network support via email & phone.Per month fixed fee for minimum 20 hours/month.", "unitAmount": 4000, "quantity": 1, "taxAmount": 800, "totalAmount": 4800, "accountRef": { "id": "f96c9458-d724-47bf-8f74-a9d5726465ce" }, "taxRateRef": { "id": "INPUT2" } }, { "description": "Stationery charges", "unitAmount": 32, "quantity": 8, "taxAmount": 51.2, "totalAmount": 307.2, "accountRef": { "id": "cba6527d-f102-4538-b421-e483233e9d5a" }, "taxRateRef": { "id": "INPUT2" } } ], "status": "Open", "totalAmount": 7267.2, "amountDue": 7267.2 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "409": { "$ref": "#/components/responses/Idempotency-Conflict" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/payables/bills/{billId}/attachments": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/billId" } ], "post": { "summary": "Upload bill attachment", "description": "The *Upload bill attachment* endpoint uploads an attachment and assigns it against a specific `billId`.\r\n\r\n[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services.", "operationId": "upload-bill-attachment", "tags": [ "Bills" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AttachmentUpload" } } } }, "responses": { "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/bills/{billId}/attachments": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/billId" } ], "get": { "tags": [ "Bills" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" }, "examples": { "Info": { "value": { "id": "422f093f-e556-4bf3-91c0-93af70c3e850", "name": "receipt.png", "contentType": "image/png", "dateCreated": "2022-10-23T00:00:00.000Z", "fileSize": 100, "includeWhenSent": true, "sourceModifiedDate": "2022-05-26T10:34:10Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } }, "operationId": "list-bill-attachments", "summary": "List bill attachments", "description": "The *List bill attachments* endpoint returns a list of attachments available to download for a given `billId`.\r\n\r\n[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services." } }, "/companies/{companyId}/connections/{connectionId}/payables/bills/{billId}/attachments/{attachmentId}/download": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/billId" }, { "$ref": "#/components/parameters/attachmentId" } ], "get": { "summary": "Download bill attachment", "description": "The *Download bill attachment* endpoint downloads a specific attachment for a given `billId` and `attachmentId`.\n\n[Bills](https://docs.codat.io/sync-for-payables-api#/schemas/Bill) are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services.\n\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=bills) for integrations that support downloading a bill attachment.\n", "operationId": "download-bill-attachment", "tags": [ "Bills" ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "title": "Data", "type": "string", "format": "binary" } } } }, "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}/payables/bills/{billId}/payment": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/billId" }, { "in": "header", "name": "Idempotency-Key", "description": "A unique identifier to ensure idempotent behaviour for subsequent requests.", "schema": { "type": "string" } } ], "post": { "summary": "Create bill payment", "description": "The *Create bill payment* endpoint creates a new [bill payment](https://docs.codat.io/sync-for-payables-api#/schemas/BillPayment) for a given company's connection.\n\n[Bill payments](https://docs.codat.io/sync-for-payables-api#/schemas/BillPayment) are an allocation of money within any Accounts Payable account.", "operationId": "create-bill-payment", "tags": [ "Bill payments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillPayment/definitions/billPaymentPrototype" }, "examples": { "Bill payment example": { "value": { "amount": 22, "currencyRate": 1, "date": "2022-10-23T00:00:00.000Z", "accountRef": { "id": "7bda9f44sr56" }, "reference": "Bill Payment against bill c13e37b6 dfaa-4894-b3be-9fe97bda9f44" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillPayment" }, "examples": { "Bill payment": { "value": { "id": "billPayment-1029932", "amount": 22, "currencyRate": 1, "date": "2022-10-23T00:00:00.000Z", "accountRef": { "id": "7bda9f44sr56" }, "reference": "Bill Payment against bill c13e37b6 dfaa-4894-b3be-9fe97bda9f44" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "409": { "$ref": "#/components/responses/Idempotency-Conflict" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/payables/suppliers": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "get": { "tags": [ "Suppliers" ], "summary": "List suppliers", "description": "The *List suppliers* endpoint returns a list of [suppliers](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) for a given company's connection.\n\n[Suppliers](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) are people or organizations that provide something, such as a product or service.\n\nBy default, this endpoint returns a list of active and archived suppliers. You can use [querying](https://docs.codat.io/using-the-api/querying) to change that. \n\nFor example, to retrieve only active suppliers (i.e. `status=Active`) or suppliers created within the specified number of days (e.g. `sourceModifiedDate>2023-12-15T00:00:00.000Z`), query the endpoint as follows: `/payables/suppliers?query=sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Active`.For example, to retrieve active suppliers modified after a particular date use `query=sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Active`.", "operationId": "list-suppliers", "parameters": [ { "$ref": "#/components/parameters/continuationToken" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "examples": { "Source modified date": { "value": "sourceModifiedDate>2023-12-15T00:00:00.000Z" }, "Status (active)": { "value": "status=Active" }, "Status (archived)": { "value": "status=Archived" }, "Status (active) & source modified date": { "value": "sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Active" }, "Status (archived) & source modified date": { "value": "sourceModifiedDate>2023-12-15T00:00:00.000Z&&status=Archived" } }, "description": "Codat query string allows you to filter by `sourceModifiedDate` or if a supplier is `Active` or `Archived` in the accounting software. Learn more about Codat's query string [here](https://docs.codat.io/using-the-api/querying)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier/definitions/suppliers" }, "examples": { "Suppliers": { "value": { "results": [ { "id": "c523e12f-8b74-4d3a-bbd8-32d7a2f598b4", "supplierName": "City Limousines", "contactName": "Martin Dale", "emailAddress": "martyd@citylim.co", "phone": "07999 999999", "addresses": [ { "type": "Billing", "line1": "Unit 51", "line2": "Bakersfield Industrial Estate", "city": "Bakersfield", "region": "California", "country": "USA", "postalcode": "93308" } ], "status": "Active", "balance": 100, "defaultCurrency": "GBP", "sourceModifiedDate": "2022-10-23T00:00:00Z" }, { "id": "41", "supplierName": "AI Support", "contactName": "AI Support", "addresses": [ { "type": "Billing", "line1": "test", "region": "string", "country": "Djibouti" } ], "status": "Active", "defaultCurrency": "GBP", "sourceModifiedDate": "2022-12-07T10:48:18Z" } ], "pagination": { "continuationToken": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==" } } } } } } }, "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" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "post": { "tags": [ "Suppliers" ], "summary": "Create supplier", "description": "The *Create supplier* endpoint creates a new [supplier](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) for a given company's connection.\r\n\r\n[Suppliers](https://docs.codat.io/sync-for-payables-api#/schemas/Supplier) are people or organizations that provide something, such as a product or service.\r\n", "operationId": "create-supplier", "parameters": [ { "in": "header", "name": "Idempotency-Key", "description": "A unique identifier to ensure idempotent behaviour for subsequent requests.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier/definitions/supplierPrototype" }, "examples": { "Suppliers": { "value": { "supplierName": "Greggs", "contactName": "Greg Greggs", "emailAddress": "greg@greggs.com", "phone": "+44 (0)1223 322410", "addresses": [ { "type": "Billing", "line1": "Flat 1", "line2": "2 Dennis Avenue", "city": "London", "region": "Camden", "country": "GBR", "postalCode": "EC1N 7TE" } ], "status": "Active", "defaultCurrency": "GBP" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" }, "examples": { "Suppliers": { "value": { "id": "sup-10933920", "supplierName": "Greggs", "contactName": "Greg Greggs", "emailAddress": "greg@greggs.com", "phone": "+44 (0)1223 322410", "address": [ { "type": "Billing", "line1": "Flat 1", "line2": "2 Dennis Avenue", "city": "London", "region": "Camden", "country": "GBR", "postalCode": "EC1N 7TE" } ], "status": "Active", "defaultCurrency": "GBP" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/payables/bankAccounts": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "post": { "tags": [ "Bank accounts" ], "summary": "Create bank account", "parameters": [ { "in": "header", "name": "Idempotency-Key", "description": "A unique identifier to ensure idempotent behaviour for subsequent requests.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccount/definitions/bankAccountPrototype" }, "examples": { "Bank account example": { "value": { "id": "fb623ab2-f6ff-4b22-b7d3-b7cc2a4aa0ea", "nominalCode": "22", "name": "Plutus - Payables - Bank Account 12", "accountNumber": "0120 0440", "sortCode": "50-50-50", "currency": "GBP", "accountType": "Debit", "status": "Active", "sourceModifiedDate": "2024-02-22T14:46:43.990Z" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccount" }, "examples": {} } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } }, "description": "The *Create bank account* endpoint creates a new [bank account](https://docs.codat.io/sync-for-payables-api#/schemas/BankAccount) for a given company's connection.\r\n\r\n[Bank accounts](https://docs.codat.io/sync-for-payables-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution.", "operationId": "create-bank-account" } } }, "webhooks": { "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." } } } }, "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": { "Address": { "title": "Address", "x-internal": true, "type": "object", "properties": { "type": { "$ref": "#/components/schemas/Address/definitions/addressType" }, "line1": { "type": "string", "nullable": true, "description": "Line 1 of the customer address." }, "line2": { "type": "string", "nullable": true, "description": "Line 2 of the customer address." }, "city": { "type": "string", "nullable": true, "description": "City of the customer address." }, "region": { "type": "string", "nullable": true, "description": "Region of the customer address." }, "country": { "type": "string", "nullable": true, "description": "Country of the customer's address. For NetSuite, use the 2-digit [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code." }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code or zip code." } }, "definitions": { "addressType": { "description": "The type of the address", "type": "string", "enum": [ "Unknown", "Billing", "Delivery" ] } } }, "Attachment": { "title": "Attachment", "description": " The Codat API supports pulling and pushing of file attachments for invoices, bills, direct costs, and direct incomes.\n\n > **Retrieving attachments**\n > \n > If a company is authorized, you can query the Codat API to read, download, and upload attachments without requiring a fresh sync of data.\n\n Unlike other data types, Codat doesn't support [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings) for attachments.\n\n Note that different integrations have different requirements for file size and extension of attachments.\n\n | Integration | File size | File extension |\n |-------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|\n | Xero | 4 MB | 7Z, BMP, CSV, DOC, DOCX, EML, GIF, JPEG, JPG, KEYNOTE, MSG, NUMBERS, ODF, ODS, ODT, PAGES, PDF, PNG, PPT, PPTX, RAR, RTF, TIF, TIFF, TXT, XLS, XLSX, ZIP |\n | QuickBooks Online | 100 MB | AI, CSV, DOC, DOCX, EPS, GIF, JPEG, JPG, ODS, PAGES, PDF, PNG, RTF, TIF, TXT, XLS, XLSX, XML |\n | NetSuite | 100 MB | BMP, CSV, XLS, XLSX, JSON, PDF, PJPG, PJPEG, PNG, TXT, SVG, TIF, TIFF, DOC, DOCX, ZIP |\n | Dynamics 365 Business Central | 350 MB | Dynamics do not explicitly outline which file types are supported but they do state here that \"You can attach any type of file, such as text, image, or video files\". |", "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for the attachment, unique for the company in the accounting software." }, "name": { "type": "string", "nullable": true, "description": "Name of the attachment file." }, "contentType": { "type": "string", "nullable": true, "description": "File type of the attachment. This is represented by appending the file type to the [IETF standard file naming requirements](https://tools.ietf.org/html/rfc6838). For example, for a jpeg file the output is **image/jpeg**.\n\nSupported file types vary per platform. " }, "dateCreated": { "$ref": "#/components/schemas/Connection/properties/created" }, "fileSize": { "type": "integer", "format": "int32", "nullable": true, "description": "File size in bytes. For example, if this reads **46153**, then the file size is 46kb." }, "includeWhenSent": { "type": "boolean", "description": "If `true`, then the attachment is included with the associated invoice, bill or direct costs when it is printed, emailed, or sent to a customer, if the underlying accounting software allows this." } } }, { "title": "Source Modified Date", "x-internal": true, "type": "object", "nullable": true, "properties": { "sourceModifiedDate": { "allOf": [ { "$ref": "#/components/schemas/Connection/properties/created" }, { "description": "The date when a record was last modified in the source platform, usually by the business or a business process. For example, when payments are made against an invoice. \n\nIt is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when:\n - Pulling attachments\n - The integration platform does not provide modification dates for a data type\n - A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred\n - A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records\n\nIn Codat's data model, dates and times are represented using the ISO 8601 standard." } ] } } } ] }, "AttachmentUpload": { "title": "Attachment upload", "type": "object", "x-internal": true, "required": [ "file" ], "properties": { "file": { "$ref": "#/components/schemas/AttachmentUpload/definitions/codatFile" } }, "definitions": { "codatFile": { "type": "string", "description": "The file to be uploaded as an attachment.", "format": "binary" } } }, "BankAccount": { "title": "Bank accounts", "type": "object", "allOf": [ { "properties": { "id": { "type": "string", "description": "Identifier for the bank account, unique for the company in the accounting software." }, "nominalCode": { "type": "string", "nullable": true, "description": "Code used to identify each nominal account for a business." }, "name": { "type": "string", "nullable": true, "description": "Name of the bank account in the accounting software." }, "accountType": { "title": "Bank Account Type", "x-internal": true, "enum": [ "Unknown", "Credit", "Debit" ], "type": "string", "description": "The type of transactions and balances on the account. \nFor Credit accounts, positive balances are liabilities, and positive transactions **reduce** liabilities. \nFor Debit accounts, positive balances are assets, and positive transactions **increase** assets." }, "accountNumber": { "type": "string", "nullable": true, "description": "Account number for the bank account.\n\nXero integrations\nOnly a UK account number shows for bank accounts with GBP currency and a combined total of sort code and account number that equals 14 digits, For non-GBP accounts, the full bank account number is populated." }, "sortCode": { "type": "string", "nullable": true, "description": "Sort code for the bank account. This is relevant to UK bank accounts.\n\nXero integrations\nThe sort code is only displayed when the currency = GBP and the sort code and account number sum to 14 digits. For non-GBP accounts, this field is not populated." }, "currency": { "$ref": "#/components/schemas/Bill/properties/currency", "description": "Base currency of the bank account." }, "status": { "$ref": "#/components/schemas/BankAccount/definitions/bankAccountStatus" } } }, { "$ref": "#/components/schemas/Attachment/allOf/1" } ], "definitions": { "bankAccountStatus": { "type": "string", "description": "The current status of the bank account.", "enum": [ "Active", "Archived" ] }, "bankAccountPrototype": { "title": "Bank account prototype", "type": "object", "properties": { "nominalCode": { "$ref": "#/components/schemas/BankAccount/allOf/0/properties/nominalCode" }, "name": { "$ref": "#/components/schemas/BankAccount/allOf/0/properties/name" }, "accountType": { "$ref": "#/components/schemas/BankAccount/allOf/0/properties/accountType" }, "accountNumber": { "$ref": "#/components/schemas/BankAccount/allOf/0/properties/accountNumber" }, "sortCode": { "$ref": "#/components/schemas/BankAccount/allOf/0/properties/sortCode" }, "currency": { "$ref": "#/components/schemas/BankAccount/allOf/0/properties/currency" } }, "required": [ "name", "accountType", "accountNumber", "currency" ] } } }, "Bill": { "title": "Bill", "description": "Bills are invoices that represent the SMB's financial obligations to their supplier for a purchase of goods or services.", "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for the bill, unique for the company in the accounting software." }, "reference": { "type": "string", "nullable": true, "description": "User-friendly reference for the bill." }, "supplierRef": { "$ref": "#/components/schemas/Supplier/definitions/supplierRef" }, "issueDate": { "allOf": [ { "description": "Date of the bill as recorded in the accounting software." }, { "$ref": "#/components/schemas/Connection/properties/created" } ] }, "dueDate": { "allOf": [ { "description": "Date the supplier is due to be paid." }, { "$ref": "#/components/schemas/Connection/properties/created" } ] }, "currency": { "title": "Currency", "x-internal": true, "type": "string", "description": "The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, e.g. _GBP_.\n\n## Unknown currencies\n\nIn line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. \n\nThere are only a very small number of edge cases where this currency code is returned by the Codat system.", "format": "ISO4217", "examples": [ "GBP", "USD", "EUR" ] }, "currencyRate": { "title": "Currency rate", "type": "number", "format": "decimal", "nullable": true, "description": "Rate to convert the total amount of the payment into the base currency for the company at the time of the payment.\n\nCurrency rates in Codat are implemented as the multiple of foreign currency units to each base currency unit. \n\nIt is not possible to perform the currency conversion with two or more non-base currencies participating in the transaction. For example, if a company's base currency is USD, and it has a bill issued in EUR, then the bill payment must happen in USD or EUR.\n\nWhere the currency rate is provided by the underlying accounting software, it will be available from Codat with the same precision (up to a maximum of 9 decimal places). \n\nFor accounting software which do not provide an explicit currency rate, it is calculated as `baseCurrency / foreignCurrency` and will be returned to 9 decimal places.\n\n## Examples with base currency of GBP\n\n| Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (GBP) |\n| :--------------- | :------------- | :------------ | :------------------------- |\n| **USD** | $20 | 0.781 | £15.62 |\n| **EUR** | €20 | 0.885 | £17.70 |\n| **RUB** | ₽20 | 0.011 | £0.22 |\n\n## Examples with base currency of USD\n\n| Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (USD) |\n| :--------------- | :------------- | :------------ | :------------------------- |\n| **GBP** | £20 | 1.277 | $25.54 |\n| **EUR** | €20 | 1.134 | $22.68 |\n| **RUB** | ₽20 | 0.015 | $0.30 |\n\n\n### Integration-specific details\n\n| Integration | Scenario | System behavior |\n|-------------------|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| QuickBooks Online | Transaction currency differs from base currency | If currency rate value is left `null`, a rate of 1 will be used by QBO by default. To override this, specify a currencyRate in the request body. |" }, "lineItems": { "type": "array", "nullable": true, "description": "Array of Bill line items.", "items": { "$ref": "#/components/schemas/Bill/definitions/billLineItem" } }, "status": { "$ref": "#/components/schemas/Bill/definitions/billStatus" }, "totalAmount": { "type": "number", "format": "decimal", "description": "Amount of the bill, including tax." }, "amountDue": { "type": "number", "format": "decimal", "nullable": true, "description": "Amount outstanding on the bill." }, "sourceModifiedDate": { "allOf": [ { "$ref": "#/components/schemas/Connection/properties/created" }, { "description": "The date when a record was last modified in the source platform, usually by the business or a business process. For example, when payments are made against an invoice. \n\nIt is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when:\n - Pulling attachments\n - The integration platform does not provide modification dates for a data type\n - A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred\n - A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records\n\nIn Codat's data model, dates and times are represented using the ISO 8601 standard." } ] } }, "required": [ "supplierRef", "issueDate", "dueDate", "currency", "status" ], "definitions": { "billPrototype": { "title": "Bill prototype", "type": "object", "properties": { "reference": { "$ref": "#/components/schemas/Bill/properties/reference" }, "supplierRef": { "$ref": "#/components/schemas/Supplier/definitions/supplierRef" }, "issueDate": { "$ref": "#/components/schemas/Bill/properties/issueDate" }, "dueDate": { "$ref": "#/components/schemas/Bill/properties/dueDate" }, "currency": { "$ref": "#/components/schemas/Bill/properties/currency" }, "currencyRate": { "$ref": "#/components/schemas/Bill/properties/currencyRate" }, "lineItems": { "$ref": "#/components/schemas/Bill/properties/lineItems" }, "status": { "$ref": "#/components/schemas/Bill/definitions/billStatus" } }, "required": [ "supplierRef", "issueDate", "dueDate", "currency", "status" ] }, "billStatus": { "description": "Current state of the bill. If creating a bill the status must be `Open`.", "type": "string", "enum": [ "Unknown", "Open", "PartiallyPaid", "Paid", "Void", "Draft" ], "example": "Open" }, "billLineItem": { "title": "Bill line item", "type": "object", "properties": { "description": { "type": "string", "nullable": true, "description": "Friendly name of the goods or services received." }, "unitAmount": { "type": "number", "format": "decimal", "description": "Unit price of the goods or service." }, "quantity": { "type": "number", "format": "decimal", "description": "Number of units of goods or services received." }, "taxAmount": { "type": "number", "format": "decimal", "description": "Amount of tax applied to the line item." }, "accountRef": { "$ref": "#/components/schemas/Bill/definitions/billAccountRef" }, "totalAmount": { "type": "number", "format": "decimal", "nullable": true, "description": "Total amount of the line, including tax." }, "taxRateRef": { "$ref": "#/components/schemas/Bill/definitions/billTaxRateRef" } }, "required": [ "quantity", "unitAmount", "taxRateRef", "accountRef" ] }, "billAccountRef": { "title": "Account reference", "type": "object", "description": "Reference to the account to which the line item is linked.", "properties": { "id": { "type": "string", "description": "'id' from the Accounts data type." } } }, "billTaxRateRef": { "title": "Tax rate reference", "type": "object", "description": "Reference to the tax rate to which the line item is linked.", "properties": { "id": { "type": "string", "description": "Unique identifier for the tax rate in the accounting software." } } }, "bills": { "title": "Bills", "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Bill" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, "BillEventWebhook": { "x-internal": true, "title": "Bill event webhook", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the bill event." }, "type": { "type": "string", "description": "Type of webhook event.", "example": "payables.bill.created" }, "createdDate": { "type": "string", "description": "The datetime in UTC of when the webhook event was produced by Codat.", "examples": [ "2022-10-23T11:03:35.000Z" ] }, "payload": { "$ref": "#/components/schemas/BillEventWebhook/definitions/billEventPayload" } }, "definitions": { "billEventPayload": { "title": "Bill event payload", "type": "object", "properties": { "companyId": { "$ref": "#/components/parameters/companyId/schema" }, "connectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "pushOperationKey": { "type": "string", "format": "uuid", "example": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "description": "Unique identifier for the push operation." }, "bill": { "$ref": "#/components/schemas/Bill" } } } } }, "BillMappingOptions": { "x-internal": true, "title": "Mapping options bills", "description": "The bill mapping options for a company's accounting software.", "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BillMappingOptions/definitions/accountMappingOption" } }, "taxRate": { "type": "array", "items": { "$ref": "#/components/schemas/BillMappingOptions/definitions/taxRateMappingOption" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "definitions": { "accountMappingOption": { "title": "Account mapping option", "type": "object", "allOf": [ { "properties": { "id": { "type": "string", "description": "Identifier for the account, unique for the company.", "example": "1b6266d1-1e44-46c5-8eb5-a8f98e03124e" }, "nominalCode": { "type": "string", "nullable": true, "description": "Reference given to each nominal account for a business. It ensures money is allocated to the correct account. This code isn't a unique identifier in the Codat system.", "example": "610" }, "name": { "type": "string", "nullable": true, "description": "Name of the account.", "example": "Accounts Payable" }, "type": { "type": "string", "nullable": true, "description": "Type of account.", "example": "Liability" }, "currency": { "$ref": "#/components/schemas/Bill/properties/currency" }, "status": { "$ref": "#/components/schemas/BillMappingOptions/definitions/accountStatus" } } }, { "$ref": "#/components/schemas/Attachment/allOf/1" } ] }, "taxRateMappingOption": { "title": "Tax rate mapping option", "type": "object", "allOf": [ { "properties": { "id": { "type": "string", "description": "Identifier for the tax rate, unique for the company in the accounting software.", "example": "d2939064-dd3a-4c0f-9865-a238c2193515" }, "name": { "type": "string", "nullable": true, "description": "Codat-augmented name of the tax rate in the accounting software." }, "code": { "type": "string", "nullable": true, "description": "Code for the tax rate from the accounting software." }, "effectiveTaxRate": { "type": "number", "format": "decimal", "nullable": true, "description": "See Effective tax rates description." }, "totalTaxRate": { "type": "number", "format": "decimal", "nullable": true, "description": "Total (not compounded) sum of the components of a tax rate." }, "status": { "title": "Tax rate status", "type": "string", "enum": [ "Active", "Archived" ], "description": "Status of the tax rate in the accounting software. \n- `Active` - An active tax rate in use by a company. \n- `Archived` - A tax rate that has been archived or is inactive in the accounting software. " } } } ] }, "accountStatus": { "type": "string", "description": "The current status of the account.", "enum": [ "Active", "Archived" ], "example": "Active" } } }, "BillPayment": { "title": "Bill payment", "type": "object", "description": "", "properties": { "id": { "type": "string", "description": "Identifier for the bill payment, unique for the company in the accounting software." }, "amount": { "type": "number", "format": "decimal", "description": "Amount of the payment in the bill currency.", "example": 1329.54 }, "date": { "allOf": [ { "$ref": "#/components/schemas/Connection/properties/created" }, { "description": "Date the bill payment was recorded in the accounting software." } ] }, "reference": { "type": "string", "nullable": true, "description": "Additional information associated with the payment.", "example": "Bill Payment against bill c13e37b6-dfaa-4894-b3be-9fe97bda9f44" }, "accountRef": { "$ref": "#/components/schemas/BillPayment/definitions/billPaymentAccountRef" }, "currencyRate": { "$ref": "#/components/schemas/Bill/properties/currencyRate" } }, "definitions": { "billPaymentPrototype": { "title": "Bill payment prototype", "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/BillPayment/properties/amount" }, "date": { "$ref": "#/components/schemas/BillPayment/properties/date" }, "reference": { "$ref": "#/components/schemas/BillPayment/properties/reference" }, "accountRef": { "$ref": "#/components/schemas/BillPayment/definitions/billPaymentAccountRef" }, "currencyRate": { "$ref": "#/components/schemas/Bill/properties/currencyRate" } }, "required": [ "amount", "date", "accountRef" ] }, "billPaymentAccountRef": { "description": "Reference to the bank account / credit card which you are using to pay the bill.", "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the bank account / credit card" } }, "required": [ "id" ] } }, "example": { "amount": 22, "date": "2022-10-23T00:00:00.000Z", "reference": "Bill Payment against bill c13e37b6 dfaa-4894-b3be-9fe97bda9f44", "accountRef": { "id": "9e32cbf8-e7d5-4d4d-a593-08d550682aab" }, "currencyRate": 1 } }, "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/ClientRateLimitResetWebhook/properties/ClientId" }, "ClientName": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/ClientName" }, "RuleId": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/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/Connection/properties/created", "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": { "title": "Client ID", "type": "string", "format": "uuid", "description": "Unique identifier for your client in Codat." }, "ClientName": { "type": "string", "description": "Name of your client in Codat." }, "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/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/Connection/properties/created", "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/Connection/properties/created", "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/sync-for-payables-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/Connection/properties/created", "nullable": true }, "created": { "$ref": "#/components/schemas/Connection/properties/created" }, "createdByUserName": { "type": "string", "description": "Name of user that created the company in Codat.", "nullable": true }, "products": { "type": "array", "items": { "type": "string" }, "description": "An array of products that are currently enabled for the company." }, "tags": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^.{1,27}$" }, "additional properties": { "type": "string", "maxLength": 100 }, "description": "A collection of user-defined key-value pairs that store custom metadata against the company." } }, "required": [ "id", "name", "redirect" ] }, "companyReference": { "title": "Company reference", "type": "object", "properties": { "id": { "$ref": "#/components/parameters/companyId/schema" }, "name": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/name" }, "description": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/description" }, "links": { "type": "object", "description": "A collection of links for the company.", "properties": { "portal": { "type": "string", "format": "uri", "description": "Link to the company page in the portal." } } }, "tags": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/tags" } } } }, "examples": [ { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "string", "redirect": "https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739", "lastSync": "2022-01-01T12:00:00.000Z", "created": "2022-01-01T12:00:00.000Z", "createdByUserName": "string", "tags": { "region": "us", "uid": "f6b0c253-16c7-4da1-a0c5-9c871e9c9d6c" }, "dataConnections": [ { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } ] } ] }, "CompanyInformation": { "title": "Company information", "type": "object", "description": "Gets the latest basic info for a company.", "properties": { "companyName": { "type": "string", "nullable": true, "description": "Name of the linked company." }, "baseCurrency": { "type": "string", "nullable": true, "description": "Currency set in the accounting software of the linked company. Used by the currency rate." } } }, "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" ] }, "Connection": { "title": "Connection", "description": "A connection represents a [company's](https://docs.codat.io/sync-for-payables-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": { "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`." }, "sourceType": { "title": "Source Type", "description": "The type of platform of the connection.", "type": "string", "enum": [ "Accounting", "Banking", "BankFeed", "Commerce", "Expense", "Other", "Unknown" ], "example": "Accounting" }, "platformName": { "type": "string", "description": "Name of integration connected to company." }, "linkUrl": { "type": "string", "format": "uri", "description": "The link URL your customers can use to authorize access to their business application.", "example": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/2e2eb431-c1fa-4dc9-93fa-d29781c12bcd/start" }, "status": { "$ref": "#/components/schemas/Connection/definitions/dataConnectionStatus" }, "lastSync": { "$ref": "#/components/schemas/Connection/properties/created", "nullable": true }, "created": { "title": "Date time", "type": "string", "examples": [ "2022-10-23T00:00:00.000Z", "2022-10-23T00:00:00.000Z" ], "description": "In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example:\n\n```\n2020-10-08T22:40:50Z\n2021-01-01T00:00:00\n```\n\n\n\nWhen syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:\n\n- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`\n- Unqualified local time: `2021-11-15T01:00:00`\n- UTC time offsets: `2021-11-15T01:00:00-05:00`\n\n> Time zones\n> \n> Not all dates from Codat will contain information about time zones. \n> Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced." }, "dataConnectionErrors": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Connection/definitions/dataConnectionError" } }, "connectionInfo": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } } }, "additionalProperties": false, "required": [ "id", "integrationId", "integrationKey", "sourceId", "platformName", "linkUrl", "status", "created", "sourceType" ], "definitions": { "dataConnectionStatus": { "title": "Data connection status", "description": "The current authorization status of the data connection.", "type": "string", "enum": [ "PendingAuth", "Linked", "Unlinked", "Deauthorized" ] }, "dataConnectionError": { "title": "Data connection error", "type": "object", "properties": { "statusCode": { "type": "string", "description": "The HTTP status code returned by the source platform when the error occurred." }, "statusText": { "type": "string", "description": "A non-numeric status code/text returned by the source platform when the error occurred." }, "errorMessage": { "type": "string", "description": "A message about a error returned by Codat." }, "erroredOnUtc": { "$ref": "#/components/schemas/Connection/properties/created" }, "status": { "title": "Error status", "description": "The current status of a transient error. Null statuses indicate that the error is not transient.", "type": "string", "nullable": true, "enum": [ "Active", "Resolved" ] }, "resolvedOnUtc": { "description": "The datetime in Utc that the error was resolved.", "nullable": true, "$ref": "#/components/schemas/Connection/properties/created" } } }, "dataConnectionSourceType": { "title": "Source Type", "description": "The type of platform of the connection.", "type": "string", "enum": [ "Accounting", "Banking", "BankFeed", "Commerce", "Expense", "Other", "Unknown" ], "example": "Accounting" } }, "example": { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } }, "Connections": { "title": "Connections", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "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/Connection/properties/created" }, "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" } ] }, "DataType": { "x-internal": true, "$ref": "#/components/schemas/DataStatus/properties/dataType" }, "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." } } } } }, "Pagination": { "title": "Pagination metadata", "x-internal": true, "type": "object", "properties": { "continuationToken": { "type": "string", "description": "A continuation token indicating there are more results to be fetched. Supply this value in the `continuationToken` query parameter in the next request to fetch the next set of results. Once no more results are available, the continuation token will not be present in the response." } } }, "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" } } } ] }, "PaymentMappingOptions": { "x-internal": true, "title": "Mapping Options Payments", "description": "Gets the bill payments mapping options for a company's accounting software", "type": "object", "properties": { "bankAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMappingOptions/definitions/bankAccountMappingOption" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "definitions": { "bankAccountMappingOption": { "title": "Bank account mapping option", "type": "object", "allOf": [ { "properties": { "id": { "type": "string", "description": "Identifier for the account, unique for the company in the accounting software.", "example": "3d5a8e00-d108-4045-8823-7f342676cffa" }, "name": { "type": "string", "nullable": true, "description": "Name of the bank account in the accounting software.", "example": "Bank of Dave current account" }, "accountNumber": { "type": "string", "nullable": true, "description": "Account number for the bank account.\n\nXero integrations\nOnly a UK account number shows for bank accounts with GBP currency and a combined total of sort code and account number that equals 14 digits, For non-GBP accounts, the full bank account number is populated." }, "nominalCode": { "type": "string", "nullable": true, "description": "Code used to identify each nominal account for a business." }, "sortCode": { "type": "string", "nullable": true, "description": "Sort code for the bank account.\n\nXero integrations\nThe sort code is only displayed when the currency = GBP and the sort code and account number sum to 14 digits. For non-GBP accounts, this field is not populated." }, "currency": { "type": "string", "nullable": true, "description": "The bank account's base currency." }, "status": { "$ref": "#/components/schemas/PaymentMappingOptions/definitions/bankAccountStatus" }, "accountType": { "$ref": "#/components/schemas/BankAccount/allOf/0/properties/accountType" } } }, { "$ref": "#/components/schemas/Attachment/allOf/1" } ] }, "bankAccountStatus": { "type": "string", "description": "The current status of the bank account.", "enum": [ "Active", "Archived" ], "example": "Active" } } }, "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/Connection/properties/created" }, "completed": { "$ref": "#/components/schemas/Connection/properties/created" }, "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/Connection/properties/created", "description": "The datetime when the push was requested." }, "completedOnUtc": { "$ref": "#/components/schemas/Connection/properties/created", "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" } ] }, "Supplier": { "title": "Supplier", "description": "Suppliers are people or organizations that provide something, such as a product or service. Use the [List suppliers](https://docs.codat.io/sync-for-payables-v2-api#/operations/list-suppliers) endpoint to retrieve a list of all suppliers for a company.\n\nSuppliers' data links to accounts payable [bills](https://docs.codat.io/sync-for-payables-v2-api#/schemas/Bill).\n ", "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for the supplier, unique to the company in the accounting software." }, "supplierName": { "type": "string", "description": "Name of the supplier as recorded in the accounting system, typically the company name." }, "contactName": { "type": "string", "nullable": true, "description": "Name of the main contact for the supplier." }, "emailAddress": { "type": "string", "nullable": true, "description": "Email address that the supplier may be contacted on." }, "phone": { "type": "string", "nullable": true, "description": "Phone number that the supplier may be contacted on.", "examples": [ "+44 25691 154789", "(877) 492-8687", "01224 658 999" ] }, "addresses": { "type": "array", "nullable": true, "description": "An array of Addresses.", "items": { "$ref": "#/components/schemas/Address" } }, "status": { "$ref": "#/components/schemas/Supplier/definitions/supplierStatus" }, "balance": { "type": "number", "format": "decimal", "nullable": true, "description": "Amount outstanding against the supplier." }, "defaultCurrency": { "type": "string", "nullable": true, "description": "Default currency the supplier's transactional data is recorded in." }, "sourceModifiedDate": { "allOf": [ { "$ref": "#/components/schemas/Connection/properties/created" }, { "description": "The date when a record was last modified in the source platform, usually by the business or a business process. For example, when payments are made against an invoice. \n\nIt is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when:\n - Pulling attachments\n - The integration platform does not provide modification dates for a data type\n - A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred\n - A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records\n\nIn Codat's data model, dates and times are represented using the ISO 8601 standard." } ] } }, "definitions": { "supplierPrototype": { "title": "Supplier prototype", "type": "object", "properties": { "supplierName": { "$ref": "#/components/schemas/Supplier/properties/supplierName" }, "contactName": { "$ref": "#/components/schemas/Supplier/properties/contactName" }, "emailAddress": { "$ref": "#/components/schemas/Supplier/properties/emailAddress" }, "phone": { "$ref": "#/components/schemas/Supplier/properties/phone" }, "addresses": { "$ref": "#/components/schemas/Supplier/properties/addresses" }, "status": { "$ref": "#/components/schemas/Supplier/definitions/supplierStatus" }, "balance": { "$ref": "#/components/schemas/Supplier/properties/balance" }, "defaultCurrency": { "$ref": "#/components/schemas/Supplier/properties/defaultCurrency" } }, "required": [ "supplierName", "status" ] }, "supplierRef": { "title": "Supplier reference", "description": "Reference to the supplier the record relates to.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string", "description": "The supplier's unique ID" }, "supplierName": { "type": "string", "nullable": true, "description": "The supplier's name" } }, "required": [ "id" ] }, "supplierStatus": { "description": "Status of the supplier.", "type": "string", "enum": [ "Unknown", "Active", "Archived" ] }, "suppliers": { "title": "Suppliers", "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Supplier" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "examples": [ { "id": "C520FFD4-F6F6-4FC2-A6D2-5D7088B2B14F", "supplierName": "Kelly's Industrial Supplies", "contactName": "Kelly Ipsum", "emailAddress": "sales@kellysupplies.com", "phone": "07999 999999", "addresses": [ { "type": "Billing", "line1": "Unit 51", "line2": "Bakersfield Industrial Estate", "city": "Bakersfield", "region": "California", "country": "USA", "postalcode": "93308" } ], "status": "Active", "amount": 100, "defaultCurrency": "GBP", "sourceModifiedDate": "2022-10-23T00:00:00Z" } ] } }, "parameters": { "attachmentId": { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "8a210b68-6988-11ed-a1eb-0242ac120002" }, "description": "Unique identifier for an attachment." }, "page": { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int32", "minimum": 1, "example": 1, "default": 1 }, "description": "Page number. [Read more](https://docs.codat.io/using-the-api/paging)." }, "pageSize": { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "example": 100, "minimum": 1, "maximum": 5000 }, "description": "Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging)." }, "query": { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "example": "id=e3334455-1aed-4e71-ab43-6bccf12092ee", "description": "Codat query string. [Read more](https://docs.codat.io/using-the-api/querying)." }, "orderBy": { "name": "orderBy", "in": "query", "required": false, "schema": { "type": "string", "example": "-modifiedDate" }, "description": "Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results)." }, "billId": { "name": "billId", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "13d946f0-c5d5-42bc-b092-97ece17923ab", "9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2", 7110701885, "EILBDVJVNUAGVKRQ" ] }, "description": "Unique identifier for a bill." }, "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." }, "continuationToken": { "name": "continuationToken", "in": "query", "required": false, "schema": { "type": "string", "example": "continuationToken=eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTAwLCJwYWdlQ291bnQiOjExfQ==" }, "description": "Retrieve the next page of results using the continuation token from the previous response." }, "statusQuery": { "name": "statusQuery", "in": "query", "required": false, "schema": { "type": "string" }, "example": "status=Archived", "description": "Codat query string allows you to filter by `status` (`status=Active||status=Archived`). [Learn more](https://docs.codat.io/using-the-api/querying) about Codat's query string." } }, "responses": { "BadRequest": { "description": "The request made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Malformed query": { "value": { "statusCode": 400, "service": "PublicApi", "error": "Error processing request - not valid.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Malformed-Query": { "description": "Your `query` parameter was not correctly formed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Malformed query": { "value": { "statusCode": 400, "service": "ClientsApi", "error": "Error parsing query - Malformed query.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } }, "Unresolved property": { "value": { "statusCode": 400, "service": "PullApi", "error": "Error parsing query - Could not resolve property isCompleted on Dataset", "correlationId": "98457fb9956b7f9b4b2fd4f6e23bb5c8", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Unauthorized": { "description": "Your API request was not properly authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Unauthorized": { "value": { "statusCode": 401, "service": "PublicApi", "error": "Unauthorized", "correlationId": "7eb40d6b415d7bcd99ce658268284056", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Payment-Required": { "description": "An account limit has been exceeded. The type of limit is described in the error property:\n\n- You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request.\n- The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan.\n- Your Free account is older than 365 days and has expired. Contact support@codat.io.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 429, "service": "PublicApi", "error": "You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Forbidden": { "description": "You are using an outdated API key or a key not associated with that resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 403, "service": "PublicApi", "error": "You are using an outdated API key or a key not associated with that resource.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Not-Found": { "description": "One or more of the resources you referenced could not be found.\nThis might be because your company or data connection id is wrong, or was already deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Data connection not found": { "value": { "statusCode": 404, "service": "PublicApi", "error": "Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found", "correlationId": "8fa2b5f4794970a4ee73758f612e8df0", "canBeRetried": "Unknown", "detailedErrorCode": 0 } }, "Company not found": { "value": { "statusCode": 404, "service": "ClientsApi", "error": "No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e", "correlationId": "0a40c2f31fc8f992fb88b0853e4166f3", "canBeRetried": "Unknown", "detailedErrorCode": 0 } }, "No data available": { "value": { "statusCode": 404, "service": "PublicApi", "error": "No data available for accounts for ID e5889b459f544926ac5b8e6756df2s", "correlationId": "0a40c2f31fc8f992fb88b0853e4166f3", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Conflict": { "description": "The data type's dataset has not been requested or is still syncing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 409, "service": "PublicApi", "error": "The data set has not been requested.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Idempotency-Conflict": { "description": "A request is in progress with the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 409, "service": "PublicApi", "error": "The data set has not been requested.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Too-Many-Requests": { "description": "Too many requests were made in a given amount of time. Wait a short period and then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 429, "service": "PublicApi", "error": "You have made too many requests in a given amount of time; please retry later.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Internal-Server-Error": { "description": "There is a problem with our server. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 500, "service": "PublicApi", "error": "There is a problem with our server. Please try again later.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } }, "Service-Unavailable": { "description": "The Codat API is temporarily offline for maintenance. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "Conflict": { "value": { "statusCode": 500, "service": "PublicApi", "error": "The Codat API is temporarily offline for maintenance. Please try again later.", "correlationId": "bc997528a9d7abb9161ef45f05d38599", "canBeRetried": "Unknown", "detailedErrorCode": 0 } } } } } } }, "securitySchemes": { "auth_header": { "name": "Authorization", "description": "The word \"Basic\" followed by a space and your API key. [API keys](https://docs.codat.io/sync-for-payables-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)" } } } }