{ "openapi": "3.1.0", "servers": [ { "description": "Production", "url": "https://api.codat.io" } ], "info": { "title": "Bank Feeds", "version": "3.0.0", "contact": { "email": "support@codat.io", "name": "Codat" }, "description": "Bank Feeds solution enables your SMB users to set up bank feeds from accounts in your application to supported accounting software.\n\nA bank feed is a connection between a source bank account in your application and a target bank account in a supported accounting software.\n\n[Explore solution](https://docs.codat.io/bank-feeds-api/overview) | [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| Source accounts | Provide and manage lists of source bank accounts. |\n| Account mapping | Extra functionality for building an account management UI. |\n| Company information | Get detailed information about a company from the underlying platform. |\n| Transactions | Create new bank account transactions for a company's connections, and see previous operations. |\n", "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": "bank-feeds-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": "Bank accounts", "description": "Access bank accounts in an SMBs accounting software." }, { "name": "Source accounts", "description": "Provide and manage lists of source bank accounts." }, { "name": "Account mapping", "description": "Extra functionality for building an account management UI." }, { "name": "Transactions", "description": "Create new bank account transactions for a company's connections, and see previous operations." }, { "name": "Company information", "description": "Get detailed information about a company from the underlying accounting software." }, { "name": "Managed bank feeds", "description": "Manage bank feed syncs for source accounts." } ], "paths": { "/companies": { "post": { "summary": "Create company", "tags": [ "Companies" ], "operationId": "create-company", "responses": { "200": { "description": "OK", "content": { "application/json": { "x-speakeasy-usage-example": true, "schema": { "$ref": "#/components/schemas/Company" }, "examples": { "With no description": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Technicalium", "description": "", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18.1950523Z", "createdByUserName": "Dan Tzabar", "products": [ "spend-insights" ], "referenceSubsidiaryCompanies": [] } }, "With a description": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Technicalium", "description": "Technology services, including web and app design and development", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18.1950523Z", "createdByUserName": "Dan Tzabar", "products": [ "spend-insights" ], "referenceSubsidiaryCompanies": [] } }, "With a tag": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Technicalium", "description": "", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18.1950523Z", "createdByUserName": "Dan Tzabar", "products": [ "spend-insights" ], "tags": { "region": "us" }, "referenceSubsidiaryCompanies": [] } } } } } }, "400": { "$ref": "#/components/responses/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/bank-feeds-api#/schemas/Company) that represents your customer in Codat. \n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-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" } } } } } } }, "get": { "summary": "List companies", "tags": [ "Companies" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies" }, "examples": { "One company": { "value": { "results": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "My Test Company", "description": "My Test Company make testing software", "platform": "", "redirect": "https://link.codat.io/company/3fa85f64-5717-4562-b3fc-2c963f66afa6", "lastSync": "2022-01-01T12:30:00.000Z", "dataConnections": [ { "id": "51baa045-4836-4317-a42e-3542e991e581", "integrationId": "1c312d69-e638-46d4-ad31-72e6c3ba8390", "integrationKey": "vjms", "sourceId": "396c3158-5dd7-481b-a7c4-a795ca31792b", "platformName": "Pandle", "linkUrl": "https://link-api.codat.io/companies/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections/51baa045-4836-4317-a42e-3542e991e581/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-01-01T11:30:00Z", "createdByUserName": "Mike Smith", "products": [ "spend-insights", "lending", "expenses-v1", "commerce" ], "referenceSubsidiaryCompanies": [] } ], "pageNumber": 1, "pageSize": 100, "totalResults": 1, "_links": { "current": { "href": "/companies?page=1&pageSize=100" }, "self": { "href": "/companies" } } } }, "List of Companies": { "value": { "results": [ { "id": "d1568dde-adf6-11ed-afa1-0242ac120002", "name": "Technicalium", "description": "Technology services, including web and app design and development", "platform": "", "redirect": "https://link.codat.io/company/d1568dde-adf6-11ed-afa1-0242ac120002", "lastSync": "2022-01-01T12:30:00.000Z", "dataConnections": [ { "id": "51baa045-4836-4317-a42e-3542e991e581", "integrationId": "1c312d69-e638-46d4-ad31-72e6c3ba8390", "integrationKey": "vjms", "sourceId": "396c3158-5dd7-481b-a7c4-a795ca31792b", "platformName": "Pandle", "linkUrl": "https://link-api.codat.io/companies/d1568dde-adf6-11ed-afa1-0242ac120002/connections/51baa045-4836-4317-a42e-3542e991e581/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-01-01T11:30:00Z", "createdByUserName": "Joe Bloggs", "products": [ "spend-insights", "lending", "payables-v2" ], "referenceSubsidiaryCompanies": [] }, { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Toft stores", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18Z", "createdByUserName": "Dan Tzabar", "products": [ "spend-insights" ], "referenceSubsidiaryCompanies": [ { "id": "c8d3af58-7011-47ce-b3f2-89faf300ef6d", "name": "Toft stores UK", "links": { "portal": "https://app.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/summary" } }, { "id": "db94eddc-9212-4568-9b5c-3eab0e325913", "name": "Toft stores US", "links": { "portal": "https://app.codat.io/companies/db94eddc-9212-4568-9b5c-3eab0e325913/summary" } } ] }, { "id": "c8d3af58-7011-47ce-b3f2-89faf300ef6d", "name": "Toft stores UK", "redirect": "https://link.codat.io/company/c8d3af58-7011-47ce-b3f2-89faf300ef6d", "dataConnections": [ { "id": "d5ab61b7-1ad0-46fd-9f9f-b6761047941e", "integrationId": "cc750323-5a47-4f28-8d8e-30fbbf2ce137", "integrationKey": "akxx", "sourceId": "9815b998-024d-4415-a40b-89903b2cad6f", "platformName": "Oracle NetSuite", "linkUrl": "https://link-api.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/connections/d5ab61b7-1ad0-46fd-9f9f-b6761047941e/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-11-10T10:45:18Z", "createdByUserName": "Dan Tzabar", "products": [ "lending", "spend-insights", "payables" ], "referenceParentCompany": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Toft stores", "links": { "portal": "https://app.codat.io/companies/ab12c58d-a678-4ebf-a159-ae99e1807bd0/summary" } }, "referenceSubsidiaryCompanies": [] }, { "id": "db94eddc-9212-4568-9b5c-3eab0e325913", "name": "Toft stores US", "redirect": "https://link.codat.io/company/db94eddc-9212-4568-9b5c-3eab0e325913", "dataConnections": [ { "id": "1e5c8c9e-27fd-4ba9-9a2a-d02ba65bc2fb", "integrationId": "cc750323-5a47-4f28-8d8e-30fbbf2ce137", "integrationKey": "akxx", "sourceId": "9815b998-024d-4415-a40b-89903b2cad6f", "platformName": "Oracle NetSuite", "linkUrl": "https://link-api.codat.io/companies/db94eddc-9212-4568-9b5c-3eab0e325913/connections/1e5c8c9e-27fd-4ba9-9a2a-d02ba65bc2fb/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-11-10T10:45:18Z", "createdByUserName": "Dan Tzabar", "products": [ "spend-insights" ], "referenceParentCompany": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Toft stores", "links": { "portal": "https://app.codat.io/companies/ab12c58d-a678-4ebf-a159-ae99e1807bd0/summary" } }, "referenceSubsidiaryCompanies": [] } ], "pageNumber": 1, "pageSize": 100, "totalResults": 3, "_links": { "current": { "href": "/companies?page=1&pageSize=100" }, "self": { "href": "/companies" } } } } } } } }, "400": { "$ref": "#/components/responses/Malformed-Query" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } }, "operationId": "list-companies", "description": "The *List companies* endpoint returns a list of [companies](https://docs.codat.io/bank-feeds-api#/schemas/Company) associated to your instances.\n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n\n## Filter by tags\n\nThe *List companies* endpoint supports the filtering of companies using [tags](https://docs.codat.io/using-the-api/managing-companies#add-metadata-to-a-company). It supports the following operators with [Codat’s query language](https://docs.codat.io/using-the-api/querying):\n\n- equals (`=`)\n- not equals (`!=`)\n- contains (`~`)\n\nFor example, you can use the querying to filter companies tagged with a specific foreign key, region, or owning team: \n- Foreign key: `uid = {yourCustomerId}`\n- Region: `region != uk`\n- Owning team and region: `region = uk && owningTeam = invoice-finance`", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "example": "region=uk && team=invoice-finance", "description": "Filter companies by tags using the \"equals\" (=), \"not equals\" (!=), and \"contains\" (~) operators with [Codat’s query language](https://docs.codat.io/using-the-api/querying)." } ] } }, "/companies/{companyId}": { "get": { "summary": "Get company", "operationId": "get-company", "description": "The *Get company* endpoint returns a single company for a given `companyId`.\n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "tags": [ "Companies" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" }, "examples": { "Simple company": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Toft stores holdings", "description": "", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18Z", "createdByUserName": "Dan Tzabar", "products": [ "spend-insights", "lending", "expenses-v1", "commerce" ], "referenceSubsidiaryCompanies": [] } }, "Parent multi-entity company": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Toft stores", "description": "", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18Z", "createdByUserName": "Dan Tzabar", "products": [ "spend-insights", "lending", "expenses-v1", "commerce" ], "referenceSubsidiaryCompanies": [ { "id": "c8d3af58-7011-47ce-b3f2-89faf300ef6d", "name": "Toft stores UK", "links": { "portal": "https://app.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/summary" } }, { "id": "db94eddc-9212-4568-9b5c-3eab0e325913", "name": "Toft stores US", "links": { "portal": "https://app.codat.io/companies/db94eddc-9212-4568-9b5c-3eab0e325913/summary" } } ] } }, "Subsidiary multi-entity company": { "value": { "id": "c8d3af58-7011-47ce-b3f2-89faf300ef6d", "name": "Toft stores UK", "description": "", "platform": "", "redirect": "https://link.codat.io/company/c8d3af58-7011-47ce-b3f2-89faf300ef6d", "dataConnections": [ { "id": "d5ab61b7-1ad0-46fd-9f9f-b6761047941e", "integrationId": "cc750323-5a47-4f28-8d8e-30fbbf2ce137", "integrationKey": "akxx", "sourceId": "9815b998-024d-4415-a40b-89903b2cad6f", "platformName": "Oracle NetSuite", "linkUrl": "https://link-api.codat.io/companies/c8d3af58-7011-47ce-b3f2-89faf300ef6d/connections/d5ab61b7-1ad0-46fd-9f9f-b6761047941e/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-11-10T10:45:18Z", "createdByUserName": "Dan Tzabar", "products": [ "spend-insights", "lending", "expenses-v1", "commerce" ], "referenceParentCompany": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Toft stores", "links": { "portal": "https://app.codat.io/companies/ab12c58d-a678-4ebf-a159-ae99e1807bd0/summary" } }, "referenceSubsidiaryCompanies": [] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "delete": { "summary": "Delete a company", "operationId": "delete-company", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "description": "The *Delete company* endpoint permanently deletes a [company](https://docs.codat.io/bank-feeds-api#/schemas/Company), its [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) and any cached data. This operation is irreversible.\n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n", "tags": [ "Companies" ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "put": { "summary": "Replace company", "description": "Use the *Replace company* endpoint to replace the existing name, description, and tags of the company. Calling the endpoint will replace existing values even if new values haven't been defined in the payload.\n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.", "operationId": "replace-company", "x-speakeasy-name-override": "replace", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "tags": [ "Companies" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "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" } } } } } } }, "patch": { "summary": "Update company", "description": "Use the *Update company* endpoint to update the name, description, or tags of the company.\n\nThe *Update company* endpoint doesn't have any required fields. If any of the fields provided are `null` or not provided, they won't be included in the update. \n\nA [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their 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/CompanyUpdateRequest" }, "examples": { "Update tags": { "value": { "tags": { "refrence": "new reference" } } }, "Update name": { "value": { "name": "New Name" } } } } } } } }, "/companies/{companyId}/accessToken": { "get": { "summary": "Get company access token", "operationId": "get-company-access-token", "x-speakeasy-name-override": "get-access-token", "description": "Use the _Get company access token_ endpoint to return an access token for the specified company ID. The token is valid for one day. \n\nThe token is required by Codat's embeddable UIs (such as [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) and [Link SDK](https://docs.codat.io/auth-flow/authorize-embedded-link)) to verify the identity of the user and improve the reliability of data provided by them.", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "tags": [ "Companies" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyAccessToken" }, "examples": { "Simple company": { "value": { "expiresIn": 86400, "accessToken": "string", "tokenType": "Bearer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections": { "get": { "summary": "List connections", "description": "List the connections for a company.", "operationId": "list-connections", "tags": [ "Connections" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connections" }, "examples": { "Connections": { "value": { "results": [ { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } ], "pageNumber": 0, "pageSize": 0, "totalResults": 0, "_links": { "self": { "href": "string" }, "current": { "href": "string" }, "next": { "href": "string" }, "previous": { "href": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/Malformed-Query" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "post": { "summary": "Create connection", "description": "Creates a connection for the company by providing a valid `platformKey`. \n\nUse the [List Integrations](https://docs.codat.io/platform-api#/operations/list-integrations) endpoint to access valid platform keys. ", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "tags": [ "Connections" ], "operationId": "create-connection", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platformKey": { "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}/data/bankAccounts": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "get": { "x-internal": true, "tags": [ "Bank accounts" ], "summary": "List bank accounts", "operationId": "list-bank-accounts", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccounts" }, "examples": { "Dynamics 365 Business Central": { "value": { "results": [ { "id": "c9a41bc7-6e5b-ed11-8c34-0022481b8b5b", "accountName": "55", "accountType": "Unknown", "nominalCode": "10500", "sortCode": "", "accountNumber": "", "iBan": "", "currency": "GBP", "balance": -352.03, "modifiedDate": "2023-03-27T14:21:10Z", "sourceModifiedDate": "2023-02-07T00:00:00", "overdraftLimit": 0, "metadata": { "isDeleted": false } }, { "id": "47020f80-60e6-ec11-82f8-0022481a77f0", "accountName": "555", "accountType": "Unknown", "nominalCode": "40300", "sortCode": "", "accountNumber": "", "iBan": "", "currency": "PLN", "balance": 661.79, "modifiedDate": "2023-03-27T14:21:10Z", "sourceModifiedDate": "2022-06-07T00:00:00", "overdraftLimit": 0, "metadata": { "isDeleted": false } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 28, "_links": { "current": { "href": "/companies/d6849caf-c146-41be-8335-b73346e3bd84/connections/60acb117-5cf5-4745-b069-491551da4066/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/d6849caf-c146-41be-8335-b73346e3bd84/connections/60acb117-5cf5-4745-b069-491551da4066/data/bankAccounts" }, "next": { "href": "/companies/d6849caf-c146-41be-8335-b73346e3bd84/connections/60acb117-5cf5-4745-b069-491551da4066/data/bankAccounts?page=2&pageSize=2" } } } }, "FreeAgent": { "value": { "results": [ { "id": "738783", "accountName": "\\w3fw", "accountType": "Debit", "sortCode": "236972", "accountNumber": "A06268209", "currency": "GBP", "balance": -10484.65, "availableBalance": -10484.65, "modifiedDate": "2023-04-25T14:19:12Z", "metadata": { "isDeleted": false } }, { "id": "738778", "accountName": "2e2bna45hy\\", "accountType": "Debit", "sortCode": "236972", "accountNumber": "D01825250", "currency": "GBP", "balance": -114.4, "availableBalance": -114.4, "modifiedDate": "2023-04-25T14:19:12Z", "metadata": { "isDeleted": false } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 82, "_links": { "current": { "href": "/companies/071ad738-68f3-4561-afd0-69bab9df0803/connections/4fd7c69f-ecc1-45f5-83f2-42ed3391e386/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/071ad738-68f3-4561-afd0-69bab9df0803/connections/4fd7c69f-ecc1-45f5-83f2-42ed3391e386/data/bankAccounts" }, "next": { "href": "/companies/071ad738-68f3-4561-afd0-69bab9df0803/connections/4fd7c69f-ecc1-45f5-83f2-42ed3391e386/data/bankAccounts?page=2&pageSize=2" } } } }, "KashFlow": { "value": { "results": [ { "id": "765768", "accountName": "16th Account", "accountType": "Unknown", "nominalCode": "70700", "currency": "GBP", "balance": 326, "availableBalance": 326, "modifiedDate": "2022-09-30T10:29:16Z" }, { "id": "765766", "accountName": "1a1a", "accountType": "Unknown", "nominalCode": "70600", "currency": "GBP", "balance": 0, "availableBalance": 0, "modifiedDate": "2022-09-30T10:29:16Z" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 56, "_links": { "current": { "href": "/companies/3a707a99-89da-4b16-a5d6-595333a16352/connections/ecab4f64-1a04-4c53-a343-bfd879f41f67/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/3a707a99-89da-4b16-a5d6-595333a16352/connections/ecab4f64-1a04-4c53-a343-bfd879f41f67/data/bankAccounts" }, "next": { "href": "/companies/3a707a99-89da-4b16-a5d6-595333a16352/connections/ecab4f64-1a04-4c53-a343-bfd879f41f67/data/bankAccounts?page=2&pageSize=2" } } } }, "Oracle NetSuite": { "value": { "results": [ { "id": "825", "accountName": "Codat Europe Bank", "accountType": "Debit", "nominalCode": "111111122222111", "currency": "GBP", "balance": 558.22, "modifiedDate": "2023-05-02T13:24:36Z", "sourceModifiedDate": "2022-07-15T11:34:02", "metadata": { "isDeleted": false } }, { "id": "826", "accountName": "Codat Europe Bank USD", "accountType": "Debit", "nominalCode": "1133221133", "currency": "USD", "modifiedDate": "2023-05-02T13:24:36Z", "sourceModifiedDate": "2021-03-26T10:31:40", "metadata": { "isDeleted": false } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 4, "_links": { "current": { "href": "/companies/d5074b08-6a34-4b06-a742-236edf5dc4f1/connections/79f8313e-210a-4dc8-b69f-ba7e5004dda7/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/d5074b08-6a34-4b06-a742-236edf5dc4f1/connections/79f8313e-210a-4dc8-b69f-ba7e5004dda7/data/bankAccounts" }, "next": { "href": "/companies/d5074b08-6a34-4b06-a742-236edf5dc4f1/connections/79f8313e-210a-4dc8-b69f-ba7e5004dda7/data/bankAccounts?page=2&pageSize=2" } } } }, "QuickBooks Desktop": { "value": { "results": [ { "id": "20000-933270541", "accountName": "Checking", "accountType": "Unknown", "nominalCode": "10100", "currency": "GBP", "balance": 46954.1, "availableBalance": 46954.1, "modifiedDate": "2023-04-26T09:12:37Z", "sourceModifiedDate": "2023-12-16T05:06:45", "metadata": { "isDeleted": false } }, { "id": "550001-1071509830", "accountName": "Petty Cash", "accountType": "Unknown", "nominalCode": "10400", "currency": "GBP", "balance": 500, "availableBalance": 500, "modifiedDate": "2023-04-26T09:12:37Z", "sourceModifiedDate": "2023-12-16T05:06:45", "metadata": { "isDeleted": false } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 3, "_links": { "current": { "href": "/companies/fc72ba08-af13-4474-b28a-01dcfa6cfb51/connections/2c26b4da-97d4-4ba9-baad-1e18b49b96ac/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/fc72ba08-af13-4474-b28a-01dcfa6cfb51/connections/2c26b4da-97d4-4ba9-baad-1e18b49b96ac/data/bankAccounts" }, "next": { "href": "/companies/fc72ba08-af13-4474-b28a-01dcfa6cfb51/connections/2c26b4da-97d4-4ba9-baad-1e18b49b96ac/data/bankAccounts?page=2&pageSize=2" } } } }, "QuickBooks Online Sandbox": { "value": { "results": [ { "id": "164", "accountName": "00", "accountType": "Debit", "nominalCode": "123567", "currency": "GBP", "balance": 0, "availableBalance": 0, "modifiedDate": "2023-04-26T09:35:57Z", "sourceModifiedDate": "2022-07-20T14:11:28Z", "metadata": { "isDeleted": false } }, { "id": "163", "accountName": "11", "accountType": "Debit", "currency": "GBP", "balance": 0, "availableBalance": 0, "modifiedDate": "2023-04-26T09:35:57Z", "sourceModifiedDate": "2022-07-20T14:11:28Z", "metadata": { "isDeleted": false } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 57, "_links": { "current": { "href": "/companies/5a7f3597-36e1-4216-86fe-289ad36088a6/connections/1f9f6013-f8a5-4278-8a47-3ab7fdb6c24c/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/5a7f3597-36e1-4216-86fe-289ad36088a6/connections/1f9f6013-f8a5-4278-8a47-3ab7fdb6c24c/data/bankAccounts" }, "next": { "href": "/companies/5a7f3597-36e1-4216-86fe-289ad36088a6/connections/1f9f6013-f8a5-4278-8a47-3ab7fdb6c24c/data/bankAccounts?page=2&pageSize=2" } } } }, "QuickBooks Online": { "value": { "results": [ { "id": "202", "accountName": "\\aa", "accountType": "Debit", "currency": "GBP", "balance": 123, "availableBalance": 123, "modifiedDate": "2023-01-18T11:02:37Z", "sourceModifiedDate": "2022-11-11T14:15:13Z" }, { "id": "193", "accountName": "1 year ago", "accountType": "Debit", "currency": "GBP", "balance": 5300.02, "availableBalance": 5300.02, "modifiedDate": "2023-01-18T11:02:37Z", "sourceModifiedDate": "2023-01-18T06:05:12Z" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 140, "_links": { "current": { "href": "/companies/10818b5e-6e6a-4ed4-a1c5-3e3efe626e87/connections/9e28a776-f4be-425b-8a3d-ad49956de2c9/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/10818b5e-6e6a-4ed4-a1c5-3e3efe626e87/connections/9e28a776-f4be-425b-8a3d-ad49956de2c9/data/bankAccounts" }, "next": { "href": "/companies/10818b5e-6e6a-4ed4-a1c5-3e3efe626e87/connections/9e28a776-f4be-425b-8a3d-ad49956de2c9/data/bankAccounts?page=2&pageSize=2" } } } }, "Sage 50 (UK)": { "value": { "results": [ { "id": "1200", "accountName": "Bank Current Account", "accountType": "Unknown", "nominalCode": "1200", "sortCode": "23-34-34", "accountNumber": "003234234", "iBan": "", "currency": "GBP", "balance": -20091.04, "availableBalance": -20091.04, "modifiedDate": "2023-03-30T14:42:37Z", "sourceModifiedDate": "2022-11-25T09:25:48", "overdraftLimit": 120000, "institution": "Lloyds Bank PLC", "metadata": { "isDeleted": false } }, { "id": "1210", "accountName": "Bank Deposit Account", "accountType": "Unknown", "nominalCode": "1210", "sortCode": "45-45-45", "accountNumber": "9/00474345", "iBan": "", "currency": "GBP", "balance": 3510, "availableBalance": 3510, "modifiedDate": "2023-03-30T14:42:37Z", "sourceModifiedDate": "2022-11-25T09:25:48", "overdraftLimit": 0, "institution": "Halifax Building Society", "metadata": { "isDeleted": false } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 6, "_links": { "current": { "href": "/companies/cf5f2a47-2990-4221-bae6-0c19c86ac304/connections/8ee4910f-4fc1-47e6-89b1-5931fb33d8f7/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/cf5f2a47-2990-4221-bae6-0c19c86ac304/connections/8ee4910f-4fc1-47e6-89b1-5931fb33d8f7/data/bankAccounts" }, "next": { "href": "/companies/cf5f2a47-2990-4221-bae6-0c19c86ac304/connections/8ee4910f-4fc1-47e6-89b1-5931fb33d8f7/data/bankAccounts?page=2&pageSize=2" } } } }, "Sage Business Cloud Accounting": { "value": { "results": [ { "id": "154d05abe9f24c4babe0f6a741dec1b9", "accountName": "Abdi Internet Bank", "accountType": "Unknown", "nominalCode": "1560", "sortCode": "010101", "accountNumber": "11111", "currency": "GBP", "balance": 49.61, "availableBalance": 49.61, "modifiedDate": "2022-10-24T14:52:53Z", "sourceModifiedDate": "2020-01-27T10:53:26Z" }, { "id": "565ce07212bc492c8c2d04f43f9f67e3", "accountName": "Abdi Live Test", "accountType": "Unknown", "nominalCode": "147852", "sortCode": "123456", "accountNumber": "1234567", "currency": "GBP", "balance": -225830.75, "availableBalance": -225830.75, "modifiedDate": "2022-10-24T14:52:53Z", "sourceModifiedDate": "2020-01-28T14:00:20Z" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 45, "_links": { "current": { "href": "/companies/390083e2-351b-407c-a3be-55081c36c182/connections/37916fb7-b4b8-4a78-8872-1751e20ee0cd/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/390083e2-351b-407c-a3be-55081c36c182/connections/37916fb7-b4b8-4a78-8872-1751e20ee0cd/data/bankAccounts" }, "next": { "href": "/companies/390083e2-351b-407c-a3be-55081c36c182/connections/37916fb7-b4b8-4a78-8872-1751e20ee0cd/data/bankAccounts?page=2&pageSize=2" } } } }, "Sage Intacct": { "value": { "results": [ { "id": "CREDITCARD:55", "accountName": "CoT Credit Card", "accountType": "Credit", "nominalCode": "10021", "currency": "GBP", "modifiedDate": "2023-04-04T16:31:46Z", "sourceModifiedDate": "2023-03-27T14:11:48", "metadata": { "isDeleted": false } }, { "id": "CREDITCARD:58", "accountName": "Cot Credit Card 2", "accountType": "Credit", "nominalCode": "11112", "currency": "GBP", "modifiedDate": "2023-04-04T16:31:46Z", "sourceModifiedDate": "2023-03-27T14:15:11", "metadata": { "isDeleted": false } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 14, "_links": { "current": { "href": "/companies/df02b289-cb16-4964-ac4d-9fd60b04538e/connections/8f457d9c-1142-4241-a07e-71d1ee2e3052/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/df02b289-cb16-4964-ac4d-9fd60b04538e/connections/8f457d9c-1142-4241-a07e-71d1ee2e3052/data/bankAccounts" }, "next": { "href": "/companies/df02b289-cb16-4964-ac4d-9fd60b04538e/connections/8f457d9c-1142-4241-a07e-71d1ee2e3052/data/bankAccounts?page=2&pageSize=2" } } } }, "Xero": { "value": { "results": [ { "id": "bd9e85e0-0478-433d-ae9f-0b3c4f04bfe4", "accountName": "Business Bank Account", "accountType": "Debit", "sortCode": "990404", "accountNumber": "987654321", "currency": "GBP", "balance": 6681.79, "modifiedDate": "2023-03-15T20:36:09Z", "sourceModifiedDate": "2023-03-15T20:35:07", "metadata": { "isDeleted": false } }, { "id": "a8d6fb1a-8c5d-4683-90ce-bf9d28fc62ba", "accountName": "Business Savings Account", "accountType": "Debit", "sortCode": "890303", "accountNumber": "876543210", "currency": "GBP", "balance": 0, "modifiedDate": "2023-03-15T20:36:09Z", "sourceModifiedDate": "2023-03-15T20:36:06", "metadata": { "isDeleted": false } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 2, "_links": { "current": { "href": "/companies/5ced9667-a310-443a-a711-958d36377141/connections/6a4bcf97-e46a-465c-abf6-c42cec8e48c0/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/5ced9667-a310-443a-a711-958d36377141/connections/6a4bcf97-e46a-465c-abf6-c42cec8e48c0/data/bankAccounts" } } } }, "Zoho Books": { "value": { "results": [ { "id": "104957000000060010", "accountName": "Abdi Test", "accountType": "Unknown", "sortCode": "112233", "accountNumber": "xxxx5678", "currency": "GBP", "balance": 69858.44, "modifiedDate": "2022-10-03T08:40:38Z", "institution": "Test Bank" }, { "id": "104957000000065002", "accountName": "Abdi Test 2", "accountType": "Unknown", "sortCode": "", "accountNumber": "", "currency": "AED", "balance": 98.03, "modifiedDate": "2022-10-03T08:40:38Z", "institution": "" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 4, "_links": { "current": { "href": "/companies/d0b68840-db50-4bc3-b88c-96e225333fea/connections/a2324b8e-60e9-451d-8eb1-0fdc8e8224df/data/bankAccounts?page=1&pageSize=2" }, "self": { "href": "/companies/d0b68840-db50-4bc3-b88c-96e225333fea/connections/a2324b8e-60e9-451d-8eb1-0fdc8e8224df/data/bankAccounts" }, "next": { "href": "/companies/d0b68840-db50-4bc3-b88c-96e225333fea/connections/a2324b8e-60e9-451d-8eb1-0fdc8e8224df/data/bankAccounts?page=2&pageSize=2" } } } } } } } }, "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" } }, "description": "The *List bank accounts* endpoint returns a list of [bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) for a given company's connection.\n\n[Bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution.\n\nBefore using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/bank-feeds-api#/operations/refresh-company-data).\n " } }, "/companies/{companyId}/connections/{connectionId}/options/bankAccounts": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "get": { "summary": "Get create/update bank account model", "x-internal": true, "tags": [ "Bank accounts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOption" }, "examples": { "Dynamics 365 Business Central": { "value": { "type": "Object", "displayName": "Bank Account", "description": "An account that bank transactions may be recorded against", "properties": { "accountName": { "type": "String", "displayName": "Name", "description": "The name of the bank account in the originating system", "required": true, "validation": { "warnings": [], "information": [ { "field": "AccountName", "details": "Needs to be of the format '{No.}-{Name}'" } ] } }, "currency": { "type": "String", "displayName": "Currency", "description": "The currency of the bank account", "required": true }, "accountNumber": { "type": "String", "displayName": "Account Number", "description": "The account number for the bank account", "required": false }, "nominalCode": { "type": "String", "displayName": "Nominal Code", "description": "The external reference given to each nominal account for a business", "required": false, "validation": { "warnings": [], "information": [ { "field": "NominalCode", "details": "Bank Account Posting Group with Nominal Account must exist" } ] } }, "sortCode": { "type": "String", "displayName": "Sort Code", "description": "The sort code for the bank account", "required": false, "validation": { "warnings": [], "information": [ { "field": "SortCode", "details": "Must have a length between 0 and 20 characters" } ] } }, "iBan": { "type": "String", "displayName": "IBAN", "description": "The international bank account number of the account. Often used when making or receiving international payments", "required": false }, "overdraftLimit": { "type": "Number", "displayName": "Overdraft Limit", "description": "The pre-arranged overdraft limit of the account", "required": false, "validation": { "warnings": [], "information": [ { "field": "OverdraftLimit", "details": "Default value is 0" } ] } } }, "required": true } }, "Exact (Netherlands)": { "value": { "type": "Object", "displayName": "Bank Account", "description": "An account that bank transactions may be recorded against", "properties": { "accountName": { "type": "String", "displayName": "Name", "description": "The name of the bank account in the originating system", "required": true }, "accountNumber": { "type": "String", "displayName": "Account Number", "description": "The account number for the bank account", "required": true, "validation": { "warnings": [ { "field": "AccountNumber", "details": "Should not exceed the maximum length of 14 characters if the specified currency is GBP." } ], "information": [] } }, "sortCode": { "type": "String", "displayName": "Sort Code", "description": "The sort code for the bank account", "required": false, "validation": { "warnings": [ { "field": "SortCode", "details": "Must be 6 characters long if the specified currency is GBP." }, { "field": "SortCode", "details": "Must be provided if the specified currency is GBP." } ], "information": [] } }, "currency": { "type": "String", "displayName": "Currency", "description": "The currency of the bank account", "required": false }, "nominalCode": { "type": "String", "displayName": "Nominal Code", "description": "The external reference given to each nominal account for a business", "required": false } }, "required": true } }, "Exact (UK)": { "value": { "type": "Object", "displayName": "Bank Account", "description": "An account that bank transactions may be recorded against", "properties": { "accountName": { "type": "String", "displayName": "Name", "description": "The name of the bank account in the originating system", "required": true }, "accountNumber": { "type": "String", "displayName": "Account Number", "description": "The account number for the bank account", "required": true, "validation": { "warnings": [ { "field": "AccountNumber", "details": "Should not exceed the maximum length of 14 characters if the specified currency is GBP." } ], "information": [] } }, "sortCode": { "type": "String", "displayName": "Sort Code", "description": "The sort code for the bank account", "required": false, "validation": { "warnings": [ { "field": "SortCode", "details": "Must be 6 characters long if the specified currency is GBP." }, { "field": "SortCode", "details": "Must be provided if the specified currency is GBP." } ], "information": [] } }, "currency": { "type": "String", "displayName": "Currency", "description": "The currency of the bank account", "required": false }, "nominalCode": { "type": "String", "displayName": "Nominal Code", "description": "The external reference given to each nominal account for a business", "required": false } }, "required": true } }, "FreeAgent": { "value": { "type": "Object", "displayName": "Bank Account", "description": "An account that bank transactions may be recorded against", "properties": { "accountName": { "type": "String", "displayName": "Name", "description": "The name of the bank account in the originating system", "required": true }, "sortCode": { "type": "String", "displayName": "Sort Code", "description": "The sort code for the bank account", "required": false, "validation": { "warnings": [ { "field": "SortCode", "details": "Must have a length between 0 and 8 characters" } ], "information": [] } }, "accountNumber": { "type": "String", "displayName": "Account Number", "description": "The account number for the bank account", "required": false }, "iBan": { "type": "String", "displayName": "IBAN", "description": "The international bank account number of the account. Often used when making or receiving international payments", "required": false }, "currency": { "type": "String", "displayName": "Currency", "description": "The currency of the bank account", "options": [ { "value": "AED", "type": "String", "displayName": "AED", "required": false }, { "value": "AMD", "type": "String", "displayName": "AMD", "required": false }, { "value": "AOA", "type": "String", "displayName": "AOA", "required": false }, { "value": "ARS", "type": "String", "displayName": "ARS", "required": false }, { "value": "AUD", "type": "String", "displayName": "AUD", "required": false }, { "value": "AWG", "type": "String", "displayName": "AWG", "required": false }, { "value": "AZN", "type": "String", "displayName": "AZN", "required": false }, { "value": "BBD", "type": "String", "displayName": "BBD", "required": false }, { "value": "BDT", "type": "String", "displayName": "BDT", "required": false }, { "value": "BGN", "type": "String", "displayName": "BGN", "required": false }, { "value": "BRL", "type": "String", "displayName": "BRL", "required": false }, { "value": "BWP", "type": "String", "displayName": "BWP", "required": false }, { "value": "CAD", "type": "String", "displayName": "CAD", "required": false }, { "value": "CHF", "type": "String", "displayName": "CHF", "required": false }, { "value": "CLP", "type": "String", "displayName": "CLP", "required": false }, { "value": "CNY", "type": "String", "displayName": "CNY", "required": false }, { "value": "COP", "type": "String", "displayName": "COP", "required": false }, { "value": "CRC", "type": "String", "displayName": "CRC", "required": false }, { "value": "CUC", "type": "String", "displayName": "CUC", "required": false }, { "value": "CUP", "type": "String", "displayName": "CUP", "required": false }, { "value": "CZK", "type": "String", "displayName": "CZK", "required": false }, { "value": "DKK", "type": "String", "displayName": "DKK", "required": false }, { "value": "DOP", "type": "String", "displayName": "DOP", "required": false }, { "value": "EGP", "type": "String", "displayName": "EGP", "required": false }, { "value": "EUR", "type": "String", "displayName": "EUR", "required": false }, { "value": "FJD", "type": "String", "displayName": "FJD", "required": false }, { "value": "GBP", "type": "String", "displayName": "GBP", "required": false }, { "value": "GEL", "type": "String", "displayName": "GEL", "required": false }, { "value": "GHS", "type": "String", "displayName": "GHS", "required": false }, { "value": "GTQ", "type": "String", "displayName": "GTQ", "required": false }, { "value": "GYD", "type": "String", "displayName": "GYD", "required": false }, { "value": "HKD", "type": "String", "displayName": "HKD", "required": false }, { "value": "HNL", "type": "String", "displayName": "HNL", "required": false }, { "value": "HRK", "type": "String", "displayName": "HRK", "required": false }, { "value": "HUF", "type": "String", "displayName": "HUF", "required": false }, { "value": "IDR", "type": "String", "displayName": "IDR", "required": false }, { "value": "ILS", "type": "String", "displayName": "ILS", "required": false }, { "value": "INR", "type": "String", "displayName": "INR", "required": false }, { "value": "ISK", "type": "String", "displayName": "ISK", "required": false }, { "value": "JMD", "type": "String", "displayName": "JMD", "required": false }, { "value": "JPY", "type": "String", "displayName": "JPY", "required": false }, { "value": "KES", "type": "String", "displayName": "KES", "required": false }, { "value": "KRW", "type": "String", "displayName": "KRW", "required": false }, { "value": "KWD", "type": "String", "displayName": "KWD", "required": false }, { "value": "KYD", "type": "String", "displayName": "KYD", "required": false }, { "value": "KZT", "type": "String", "displayName": "KZT", "required": false }, { "value": "LAK", "type": "String", "displayName": "LAK", "required": false }, { "value": "LBP", "type": "String", "displayName": "LBP", "required": false }, { "value": "LKR", "type": "String", "displayName": "LKR", "required": false }, { "value": "LTL", "type": "String", "displayName": "LTL", "required": false }, { "value": "LVL", "type": "String", "displayName": "LVL", "required": false }, { "value": "MAD", "type": "String", "displayName": "MAD", "required": false }, { "value": "MDL", "type": "String", "displayName": "MDL", "required": false }, { "value": "MGA", "type": "String", "displayName": "MGA", "required": false }, { "value": "MUR", "type": "String", "displayName": "MUR", "required": false }, { "value": "MVR", "type": "String", "displayName": "MVR", "required": false }, { "value": "MWK", "type": "String", "displayName": "MWK", "required": false }, { "value": "MXN", "type": "String", "displayName": "MXN", "required": false }, { "value": "MYR", "type": "String", "displayName": "MYR", "required": false }, { "value": "MZN", "type": "String", "displayName": "MZN", "required": false }, { "value": "NAD", "type": "String", "displayName": "NAD", "required": false }, { "value": "NGN", "type": "String", "displayName": "NGN", "required": false }, { "value": "NOK", "type": "String", "displayName": "NOK", "required": false }, { "value": "NPR", "type": "String", "displayName": "NPR", "required": false }, { "value": "NZD", "type": "String", "displayName": "NZD", "required": false }, { "value": "OMR", "type": "String", "displayName": "OMR", "required": false }, { "value": "PEN", "type": "String", "displayName": "PEN", "required": false }, { "value": "PHP", "type": "String", "displayName": "PHP", "required": false }, { "value": "PKR", "type": "String", "displayName": "PKR", "required": false }, { "value": "PLN", "type": "String", "displayName": "PLN", "required": false }, { "value": "QAR", "type": "String", "displayName": "QAR", "required": false }, { "value": "RON", "type": "String", "displayName": "RON", "required": false }, { "value": "RSD", "type": "String", "displayName": "RSD", "required": false }, { "value": "RUB", "type": "String", "displayName": "RUB", "required": false }, { "value": "RWF", "type": "String", "displayName": "RWF", "required": false }, { "value": "SAR", "type": "String", "displayName": "SAR", "required": false }, { "value": "SCR", "type": "String", "displayName": "SCR", "required": false }, { "value": "SEK", "type": "String", "displayName": "SEK", "required": false }, { "value": "SGD", "type": "String", "displayName": "SGD", "required": false }, { "value": "THB", "type": "String", "displayName": "THB", "required": false }, { "value": "TND", "type": "String", "displayName": "TND", "required": false }, { "value": "TRY", "type": "String", "displayName": "TRY", "required": false }, { "value": "TTD", "type": "String", "displayName": "TTD", "required": false }, { "value": "TWD", "type": "String", "displayName": "TWD", "required": false }, { "value": "TZS", "type": "String", "displayName": "TZS", "required": false }, { "value": "UAH", "type": "String", "displayName": "UAH", "required": false }, { "value": "UGX", "type": "String", "displayName": "UGX", "required": false }, { "value": "USD", "type": "String", "displayName": "USD", "required": false }, { "value": "UYU", "type": "String", "displayName": "UYU", "required": false }, { "value": "VEF", "type": "String", "displayName": "VEF", "required": false }, { "value": "VND", "type": "String", "displayName": "VND", "required": false }, { "value": "VUV", "type": "String", "displayName": "VUV", "required": false }, { "value": "XAF", "type": "String", "displayName": "XAF", "required": false }, { "value": "XCD", "type": "String", "displayName": "XCD", "required": false }, { "value": "XOF", "type": "String", "displayName": "XOF", "required": false }, { "value": "ZAR", "type": "String", "displayName": "ZAR", "required": false }, { "value": "ZMK", "type": "String", "displayName": "ZMK", "required": false } ], "required": true }, "balance": { "type": "Number", "displayName": "Balance", "description": "The balance of the bank account", "required": false, "validation": { "warnings": [], "information": [ { "field": "Balance", "details": "The opening balance, in the account currency" } ] } }, "institution": { "type": "String", "displayName": "Institution", "description": "The institution of the bank account", "required": false } }, "required": true } }, "KashFlow": { "value": { "type": "Object", "displayName": "Bank Account", "description": "An account that bank transactions may be recorded against", "properties": { "accountName": { "type": "String", "displayName": "Account Name", "description": "Name of the bank account as it appears in Kashflow.", "required": true }, "balance": { "type": "Number", "displayName": "Balance", "description": "The opening balance, in the account currency.", "required": false }, "currency": { "type": "String", "displayName": "Currency", "description": "The currency of the bank account.", "required": true } }, "required": true } }, "QuickBooks Desktop": { "value": { "type": "Object", "displayName": "Bank Account", "description": "An account that bank transactions may be recorded against", "properties": { "nominalCode": { "type": "String", "displayName": "Nominal Code", "description": "The external reference given to each nominal account for a business", "required": true, "validation": { "warnings": [ { "field": "NominalCode", "details": "Max length of 7 characters." } ], "information": [] } }, "accountName": { "type": "String", "displayName": "Name", "description": "The name of the bank account in the originating system", "required": true, "validation": { "warnings": [ { "field": "AccountName", "details": "Max length of 31 characters." } ], "information": [] } }, "currency": { "type": "String", "displayName": "Currency", "description": "The currency of the bank account", "required": false, "validation": { "warnings": [ { "field": "Currency", "details": "The currency must match the base currency of the QuickBooks Desktop company unless the FullyQualifiedCategory is 'Asset.AccountsReceivable','Liability.AccountsPayable' or 'Liability.CreditCard'" }, { "field": "Currency", "details": "Must be a three letter ISO code that matches an existing active currency in the QuickBooks Desktop company" }, { "field": "Currency", "details": "Can only be set if the QuickBooks Desktop company has Multicurrency enabled." } ], "information": [ { "field": "Currency", "details": "If not set, will default to the base currency of the QuickBooks Desktop company" } ] } }, "balance": { "type": "Number", "displayName": "Balance", "description": "The balance of the bank account", "required": false } }, "required": true } }, "QuickBooks Online Sandbox": { "value": { "type": "Object", "displayName": "Bank Account", "description": "An account that bank transactions may be recorded against", "properties": { "accountName": { "type": "String", "displayName": "Account Name", "description": "Name of account as it appears in the chart of accounts or general ledger.", "required": true }, "accountNumber": { "type": "String", "displayName": "Account Number", "description": "User-defined account number to help the user in identifying the account within the chart-of-accounts and in deciding what should be posted to the account.", "required": true }, "currency": { "type": "String", "displayName": "Currency", "description": "Currency of the bank account.", "required": true } }, "required": true } }, "Sage Business Cloud Accounting": { "value": { "type": "Object", "displayName": "Bank Account", "description": "An account that bank transactions may be recorded against", "properties": { "accountName": { "type": "String", "displayName": "Name", "description": "The name of the bank account in the originating system", "required": true, "validation": { "warnings": [], "information": [ { "field": "AccountName", "details": "Must be provided." }, { "field": "AccountName", "details": "Should not be longer than 50 characters." } ] } }, "currency": { "type": "String", "displayName": "Currency", "description": "The currency of the bank account", "required": true, "validation": { "warnings": [], "information": [ { "field": "Currency", "details": "Must be provided." }, { "field": "Currency", "details": "Must match the company's base currency." } ] } }, "sortCode": { "type": "String", "displayName": "Sort Code", "description": "The sort code for the bank account", "required": false, "validation": { "warnings": [], "information": [ { "field": "SortCode", "details": "Should be a 6 digit number." } ] } }, "accountNumber": { "type": "String", "displayName": "Account Number", "description": "The account number for the bank account", "required": false, "validation": { "warnings": [], "information": [ { "field": "AccountNumber", "details": "Should not be longer than 25 characters." } ] } }, "iBan": { "type": "String", "displayName": "IBAN", "description": "The international bank account number of the account. Often used when making or receiving international payments", "required": false, "validation": { "warnings": [], "information": [ { "field": "IBan", "details": "Should be in the international bank account number format." } ] } }, "nominalCode": { "type": "String", "displayName": "Nominal Code", "description": "The external reference given to each nominal account for a business", "required": false, "validation": { "warnings": [], "information": [ { "field": "NominalCode", "details": "Should be a number between 1 and 99999999." } ] } } }, "required": true } }, "Sandbox": { "value": { "type": "Object", "displayName": "Bank Account", "description": "An account that bank transactions may be recorded against", "properties": { "accountName": { "type": "String", "displayName": "Name", "description": "The name of the bank account in the originating system", "required": true }, "accountType": { "type": "String", "displayName": "Account Type", "description": "The type of account", "required": true }, "nominalCode": { "type": "String", "displayName": "Nominal Code", "description": "The external reference given to each nominal account for a business", "required": true }, "sortCode": { "type": "String", "displayName": "Sort Code", "description": "The sort code for the bank account", "required": true }, "accountNumber": { "type": "String", "displayName": "Account Number", "description": "The account number for the bank account", "required": true }, "iBan": { "type": "String", "displayName": "IBAN", "description": "The international bank account number of the account. Often used when making or receiving international payments", "required": true }, "currency": { "type": "String", "displayName": "Currency", "description": "The currency of the bank account", "required": true }, "balance": { "type": "Number", "displayName": "Balance", "description": "The balance of the bank account", "required": true }, "availableBalance": { "type": "Number", "displayName": "Available Balance", "description": "The available balance of the bank account", "required": true }, "overdraftLimit": { "type": "Number", "displayName": "Overdraft Limit", "description": "The pre-arranged overdraft limit of the account", "required": true }, "institution": { "type": "String", "displayName": "Institution", "description": "The institution of the bank account", "required": true }, "metadata": { "type": "Object", "displayName": "Metadata", "description": "Miscellaneous data about the item", "properties": { "isDeleted": { "type": "Boolean", "displayName": "IsDeleted", "description": "A boolean to indicate whether the object has been deleted", "required": true } }, "required": true } }, "required": true } } } } } }, "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": "get-create-bankAccounts-model", "description": "The *Get create/update bank account model* endpoint returns the expected data for the request payload when creating and updating a [bank account](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) for a given company and integration.\r\n\r\n[Bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution.\r\n\r\n**Integration-specific behavior**\r\n\r\nSee the *response examples* for integration-specific indicative models.\r\n" } }, "/companies/{companyId}/connections/{connectionId}/push/bankAccounts": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "post": { "x-internal": true, "tags": [ "Bank accounts" ], "summary": "Create bank account", "parameters": [ { "$ref": "#/components/parameters/timeoutInMinutes" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccounts/allOf/0/properties/results/items/definitions/bankAccountPrototype" }, "examples": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccounts/allOf/0/properties/results/items/definitions/bankAccountCreateResponse" }, "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/bank-feeds-api#/schemas/BankAccount) for a given company's connection.\r\n\r\n[Bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution.\r\n\r\n**Integration-specific behavior**\r\n\r\nRequired data may vary by integration. To see what data to post, first call [Get create/update bank account model](https://docs.codat.io/bank-feeds-api#/operations/get-create-update-bankAccounts-model).", "operationId": "create-bank-account" } }, "/companies/{companyId}/connections/{connectionId}/connectionInfo/bankFeedAccounts/batch": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "post": { "tags": [ "Source accounts" ], "summary": "Create source accounts", "description": "The _Batch create source accounts_ endpoint allows you to create multiple representations of your SMB's bank accounts within Codat's domain. The company can then map the source account to an existing or new target account in their accounting software.\n\n> ### Versioning\n> If you are integrating the Bank Feeds solution with Codat after August 1, 2024, please use the v2 version of the API, as detailed in the schema below. For integrations completed before August 1, 2024, select the v1 version from the schema dropdown below.", "operationId": "create-batch-source-account", "x-speakeasy-name-override": "create-batch", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SourceAccountV2/definitions/sourceAccountV2Prototype" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SourceAccount/definitions/sourceAccountPrototype" } } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SourceAccountV2BatchCreateResponse" }, { "$ref": "#/components/schemas/SourceAccountBatchCreateResponse" } ] } } } } }, "207": { "description": "Multi-Status", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SourceAccountV2BatchCreateResponse" }, { "$ref": "#/components/schemas/SourceAccountBatchCreateResponse" }, { "$ref": "#/components/schemas/SourceAccountBatchErrorResponse" } ] } } } } }, "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": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SourceAccountV2BatchCreateResponse" }, { "$ref": "#/components/schemas/SourceAccountBatchCreateResponse" }, { "$ref": "#/components/schemas/SourceAccountBatchErrorResponse" } ] } } } } }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/connectionInfo/bankFeedAccounts": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "post": { "tags": [ "Source accounts" ], "summary": "Create single source account", "description": "The _Create Source Account_ endpoint allows you to create a representation of a bank account within Codat's domain. The company can then map the source account to an existing or new target account in their accounting software.\n\n> ### Versioning\n> If you are integrating the Bank Feeds solution with Codat after August 1, 2024, please use the v2 version of the API, as detailed in the schema below. For integrations completed before August 1, 2024, select the v1 version from the schema dropdown below.", "operationId": "create-source-account", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SourceAccountV2/definitions/sourceAccountV2Prototype" }, { "$ref": "#/components/schemas/SourceAccount/definitions/sourceAccountPrototype" } ] }, "examples": { "Version 2": { "value": { "id": "acc-001", "accountName": "account-081", "accountType": "checking", "accountNumber": "12345670", "routingInfo": { "bankCode": "021001088", "type": "bankcode" }, "currency": "GBP", "balance": 99.99, "accountInfo": { "description": "account description 1", "nickname": "account 123", "accountOpenDate": "2023-05-06", "availableBalance": 10 }, "modifiedDate": "2024-08-02T00:00:00.000Z" } }, "Version 1": { "value": { "id": "acc-002", "accountName": "account-081", "sortCode": "123456", "accountType": "Credit", "accountNumber": "12345670", "currency": "GBP", "balance": 99.99, "modifiedDate": "2023-01-09T14:14:14.1057478Z" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SourceAccountV2" }, { "$ref": "#/components/schemas/SourceAccount" } ] }, "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" } } }, "get": { "tags": [ "Source accounts" ], "summary": "List source accounts", "description": "The _List source accounts_ endpoint returns a list of [source accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankFeedAccount) for a given company's connection.\n\n[Source accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankFeedAccount) are the bank's bank account within Codat's domain from which transactions are synced into the accounting platform.\n\n> ### Versioning\n> If you are integrating the Bank Feeds solution with Codat after August 1, 2024, please use the v2 version of the API, as detailed in the schema below. For integrations completed before August 1, 2024, select the v1 version from the schema dropdown below.", "operationId": "list-source-accounts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SourceAccountV2/definitions/sourceAccounts" }, { "$ref": "#/components/schemas/SourceAccount/definitions/sourceAccounts" } ] }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/connectionInfo/bankFeedAccounts/{accountId}": { "patch": { "tags": [ "Source accounts" ], "summary": "Update source account", "description": "The _Update source account_ endpoint updates a single source account for a single data connection connected to a single company.\n\n### Tips and pitfalls\n\n* This endpoint makes it possible to update the `accountName`, `status`, and `balance` fields.\n * The `status` field can only be updated to 'disconnected'.\n * The `balance` field can only be updated on accounts that are **not** 'connected'.\n* Updates made here apply exclusively to source accounts and will not affect target accounts in the accounting software.", "operationId": "update-source-account", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/accountId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAccount" }, "examples": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "x-speakeasy-usage-example": true, "schema": { "$ref": "#/components/schemas/SourceAccount" }, "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" } } }, "delete": { "tags": [ "Source accounts" ], "summary": "Delete source account", "description": "The _Delete source account_ endpoint enables you to remove a source account.\n\nRemoving a source account will also remove any mapping between the source bank feed bank accounts and the target bankfeed bank account.\n", "operationId": "delete-source-account", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/accountId" } ], "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" } } } }, "/companies/{companyId}/connections/{connectionId}/connectionInfo/bankFeedAccounts/credentials": { "post": { "tags": [ "Source accounts" ], "summary": "Generate source account credentials", "description": "The _Generate bank account credentials_ endpoint can be used to generate credentials for QuickBooks Online to authenticate the Bank Feed in the QBO portal. Each time this endpoint is called, a new set of credentials will be generated.\n\nThe old credentials will still be valid until the revoke credentials endpoint is used, which will revoke all credentials associated to the data connection.\n\n> **For QuickBooks Online only**\n>\n> Only call this endpoint when onboarding SMBs that use QuickBooks Online.", "operationId": "generate-credentials", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCredentials" } } } }, "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": { "tags": [ "Source accounts" ], "summary": "Delete all source account credentials", "x-speakeasy-name-override": "delete-credentials", "description": "The _Delete Bank Account Credentials_ endpoint serves as a comprehensive mechanism for revoking all existing authorization credentials that a company employs to establish its Bank Feed connection.\n\nIn cases where multiple credential sets have been generated, a single API call to this endpoint revokes all of them.", "operationId": "delete-bank-feed-credentials", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "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" } } } }, "/companies/{companyId}/connections/{connectionId}/bankFeedAccounts/mapping": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "get": { "tags": [ "Account mapping" ], "summary": "List bank feed accounts", "description": "The *List bank accounts* endpoint returns information about a source bank account and any current or potential target mapping accounts.\n\nA bank feed account mapping is a specified link between the source account (provided by the Codat user) and the target account (the end user's account in the underlying software).\n\n> **For custom builds only**\n> \n> Only use this endpoint if you are building your own account management UI.", "operationId": "get-bank-account-mapping", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankFeedMapping/definitions/bankFeedMappings" }, "examples": { "Example": { "value": [ { "sourceAccountId": "account-001", "status": "pending", "targetAccountOptions": [ { "name": "Money Bank account", "id": "d21e25d6-98c5-4bfb-b469-105833bea3c8", "accountNumber": "789", "sortCode": "123456" }, { "name": "Bank of Dave account", "id": "d06ff4b2-e4f2-4681-9841-014bd008cdab", "accountNumber": "99887766", "sortCode": "998866" }, { "name": "LuxLend account", "id": "c8f252fc-84f3-4a8b-ace8-ae99f41a81ae", "accountNumber": "123456789", "sortCode": "123456" } ], "sourceAccountName": "account-001", "sourceAccountNumber": "12345670", "sourceBalance": 99.99, "sourceCurrency": "GBP" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "post": { "tags": [ "Account mapping" ], "summary": "Create bank feed account mapping", "description": "The *Create bank account mapping* endpoint creates a new mapping between a source bank account and a potential account in the accounting software (target account).\n\nA bank feed account mapping is a specified link between the source account (provided by the Codat user) and the target account (the end user's account in the underlying software).\n\nTo find valid target account options, first call the [List bank feed account mappings](https://docs.codat.io//bank-feeds-api#/operations/get-bank-account-mapping) endpoint.\n\n> **For custom builds only**\n>\n> Only use this endpoint if you are building your own account management UI.\n\n#### Account mapping variability\n\nThe method of mapping the source account to the target account varies depending on the accounting software your company uses.\n\n#### Mapping options:\n\n1. **API Mapping**: Integrate the mapping journey directly into your application for a seamless user experience.\n2. **Codat UI Mapping**: If you prefer a quicker setup, you can utilize Codat's provided user interface for mapping.\n3. **Accounting Platform Mapping**: For some accounting software, the mapping process must be conducted within the software itself.\n\n### Integration-specific behavior\n\n| Bank Feed Integration | API Mapping | Codat UI Mapping | Accounting Platform Mapping |\n| --------------------- | ----------- | ---------------- | --------------------------- |\n| Xero | ✅ | ✅ | |\n| FreeAgent | ✅ | ✅ | |\n| Oracle NetSuite | ✅ | ✅ | |\n| Exact Online (NL) | ✅ | ✅ | |\n| QuickBooks Online | | | ✅ |\n| Sage | | | ✅ |", "operationId": "create-bank-account-mapping", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankFeedAccountMapping" }, "examples": { "Example": { "value": { "sourceAccountId": "acc-002", "targetAccountId": "account-081" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankFeedAccountMappingResponse" }, "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" } } } }, "/companies/{companyId}/connections/{connectionId}/bankFeeds/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### Supported Integrations\n| Integration | Supported |\n|-----------------------|-----------|\n| Oracle NetSuite | Yes |\n| Xero | Yes |\n| Exact | No |\n| FreeAgent | No |\n| Sage | No |\n| QuickBooks Online | No |", "operationId": "get-company-information", "tags": [ "Company information" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInformation" }, "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" } } } }, "/companies/{companyId}/connections/{connectionId}/push/bankAccounts/{accountId}/bankTransactions": { "post": { "tags": [ "Transactions" ], "summary": "Create bank transactions", "description": "The *Create bank transactions* endpoint creates new [bank transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) for a given company's connection.\n\n[Bank transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) are records of monetary amounts that have moved in and out of an SMB's bank account.\n\n**Integration-specific behavior**\n\nThe required properties may vary based on the integration. For detailed requirements specific to each accounting software, refer to the API reference examples.\nAlternatively, you can view the [Get create bank transaction model](https://docs.codat.io/bank-feeds-api#/operations/get-create-bank-transactions-model) for more information.", "operationId": "create-bank-transactions", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/timeoutInMinutes" }, { "name": "allowSyncOnPushComplete", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "Allow a sync upon push completion." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBankTransactions" }, "examples": { "Xero": { "value": { "accountId": "49cd5a42-b311-4750-9361-52e2ed1d4653", "transactions": [ { "id": "716422529", "date": "2023-08-22T10:21:00", "description": "Repayment of Credit Card", "counterparty": "Bank of Example", "reference": "Ref-12345", "reconciled": true, "amount": 100, "balance": 100, "transactionType": "Credit" }, { "id": "716422530", "date": "2023-08-22T10:22:00", "description": "Amazon Purchase", "counterparty": "Amazon", "reference": "Ref-12346", "reconciled": false, "amount": -100, "balance": 0, "transactionType": "Debit" }, { "id": "716422531", "date": "2023-08-22T10:23:00", "description": "Office Supplies", "counterparty": "Office Mart", "reference": "Ref-12347", "reconciled": false, "amount": -60, "balance": -60, "transactionType": "Debit" } ] } }, "QuickBooks Online Bank Feeds": { "value": { "accountId": "49cd5a42-b311-4750-9361-52e2ed1d4653", "transactions": [ { "id": "716422529", "date": "2023-08-22T10:21:00", "description": "Repayment of Credit Card", "amount": 100, "balance": 100, "transactionType": "Credit" }, { "id": "716422530", "date": "2023-08-22T10:22:00", "description": "Amazon Purchase", "amount": -100, "balance": 0, "transactionType": "Debit" }, { "id": "716422531", "date": "2023-08-22T10:23:00", "description": "Office Supplies", "amount": -60, "balance": -60, "transactionType": "Debit" } ] } }, "FreeAgent": { "value": { "accountId": "49cd5a42-b311-4750-9361-52e2ed1d4653", "transactions": [ { "id": "716422529", "date": "2023-08-22T10:21:00", "description": "Repayment of Credit Card", "amount": 100, "transactionType": "Credit" }, { "id": "716422530", "date": "2023-08-22T10:22:00", "description": "Amazon Purchase", "amount": -100, "transactionType": "Debit" }, { "id": "716422531", "date": "2023-08-22T10:23:00", "description": "Office Supplies", "amount": -60, "transactionType": "Debit" } ] } }, "Sage": { "value": { "accountId": "49cd5a42-b311-4750-9361-52e2ed1d4653", "transactions": [ { "id": "716422529", "date": "2023-08-22T10:21:00", "description": "Repayment of Credit Card", "counterparty": "Bank of Example", "reference": "Ref-12345", "amount": 100, "balance": 100, "transactionType": "Credit" }, { "id": "716422530", "date": "2023-08-22T10:22:00", "description": "Amazon Purchase", "counterparty": "Amazon", "reference": "Ref-12346", "amount": -100, "balance": 0, "transactionType": "Debit" }, { "id": "716422531", "date": "2023-08-22T10:23:00", "description": "Office Supplies", "counterparty": "Office Mart", "reference": "Ref-12347", "amount": -60, "balance": -60, "transactionType": "Debit" } ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBankTransactionsResponse" } } } }, "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}/options/bankAccounts/{accountId}/bankTransactions": { "get": { "tags": [ "Transactions" ], "summary": "Get create bank transactions model", "description": "The *Get create bank account transactions model* endpoint returns the expected data for the request payload when creating [bank account transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) for a given company and integration.\n\n[Bank account transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) are records of money that has moved in and out of an SMB's bank account.\n\n**Integration-specific behavior**\n\nSee the *response examples* for integration-specific indicative models.", "operationId": "get-create-bank-transactions-model", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOption" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/push/{pushOperationKey}": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "schema": { "type": "string", "format": "uuid" }, "name": "pushOperationKey", "in": "path", "required": true, "description": "Push operation key." } ], "get": { "summary": "Get create operation", "tags": [ "Transactions" ], "operationId": "get-create-operation", "x-speakeasy-name-override": "get-create-operation", "description": "The **Get create operation** endpoint returns a specific [write operation](/using-the-api/push) identified by the `pushOperationKey` that was performed on the company.\n\nWrite operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software.\n\nFor bank feeds, your push operations will only relate to the `bankTransactions` data type.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOperation" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/push": { "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "get": { "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "summary": "List create operations", "tags": [ "Transactions" ], "operationId": "list-create-operations", "x-speakeasy-name-override": "list-create-operations", "description": "The **List create operations** endpoint returns a list of [write operations](/using-the-api/push) performed on the company.\n\nWrite operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software. \n\nFor bank feeds, use this endpoint to view write operations related to the `bankTransactions` data type.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOperations" }, "examples": {} } } }, "400": { "$ref": "#/components/responses/Malformed-Query" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } }, "/companies/{companyId}/connections/{connectionId}/bankFeedAccounts/{sourceAccountId}/managedBankFeeds/syncs/{syncId}": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "name": "sourceAccountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the source bank account." }, { "name": "syncId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the sync." } ], "get": { "tags": [ "Managed bank feeds" ], "summary": "Get sync", "operationId": "get-managed-bank-feed-sync", "x-speakeasy-name-override": "get-sync", "description": "The _Get sync_ endpoint returns the [sync status](https://docs.codat.io/bank-feeds-api#/schemas/SyncStatusResult) for a given 'syncId'. \n\nA sync is a single execution that fetches bank transactions from a connected bank account and records them in the company's accounting software.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatusResult" } } } }, "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}/bankFeedAccounts/{sourceAccountId}/managedBankFeeds/syncs/latest": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "name": "sourceAccountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the source bank account." } ], "get": { "tags": [ "Managed bank feeds" ], "summary": "Get latest sync", "operationId": "get-latest-managed-bank-feed-sync", "x-speakeasy-name-override": "get-latest-sync", "description": "The _Get latest sync_ endpoint returns the status for a given source account's [most recent sync](https://docs.codat.io/bank-feeds-api#/schemas/SyncStatusResult). \n\nA sync is a single execution that fetches bank transactions from a connected bank account and records them in the company's accounting software.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatusResult" } } } }, "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" } } } }, "/companies/{companyId}/connections/{connectionId}/bankFeedAccounts/{sourceAccountId}/managedBankFeeds/syncs": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "name": "sourceAccountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the source bank account." } ], "post": { "tags": [ "Managed bank feeds" ], "summary": "Run ad-hoc sync", "operationId": "run-managed-bank-feed-ad-hoc-sync", "x-speakeasy-name-override": "run-ad-hoc-sync", "description": "The _Run ad-hoc sync_ endpoint immediately runs a sync with a fetch period from the last successful sync to the execution time of the new sync.\n\nA sync is a single execution that fetches bank transactions from a connected bank account and records them in the company's accounting software.\n\nUse either the [_Get latest sync_](https://docs.codat.io/bank-feeds-api#/operations/get-latest-managed-bank-feed-sync) endpoint or the [_Get sync_](https://docs.codat.io/bank-feeds-api#/operations/fetch-managed-bank-feed-sync-by-id) endpoint to get the result of this sync.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartScheduledSyncResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } } } }, "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." } } } }, "bankFeeds.sourceAccount.connected": { "post": { "description": "Triggered when a bank feed source account has become connected to a target account. This occurs when a user sets up mapping between the two.", "x-svix-feature-flag": "bank-feeds", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAccountWebhook" }, "examples": { "Connected": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "eventType": "bankFeeds.sourceAccount.connected", "generatedDate": "2022-10-23T00:00:00.000Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Toft stores", "description": "Requested early access to the new financing scheme.", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" } }, "connectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "sourceAccount": { "id": "acc-002", "accountName": "account-081", "sortCode": "040004", "accountNumber": "12345678", "currency": "GBP", "balance": 99.99, "modifiedDate": "2023-01-09T14:14:14.1057478Z", "status": "pending" } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "bankFeeds.sourceAccount.disconnected": { "post": { "description": "Called when a bank feed source account has become disconnected.", "x-svix-feature-flag": "bank-feeds", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAccountWebhook" }, "examples": { "Disconnected": { "value": { "id": "ba29118f-5406-4e59-b05c-ba307ca38d01", "eventType": "bankFeeds.sourceAccount.disconnected", "generatedDate": "2022-10-23T00:00:00.000Z", "payload": { "referenceCompany": { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "Toft stores", "description": "Requested early access to the new financing scheme.", "links": { "portal": "https://app.codat.io/companies/0498e921-9b53-4396-a412-4f2f5983b0a2/summary" } }, "connectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "sourceAccount": { "id": "acc-002", "accountName": "account-081", "sortCode": "040004", "accountNumber": "12345678", "currency": "GBP", "balance": 99.99, "modifiedDate": "2023-01-09T14:14:14.1057478Z", "status": "pending" } } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } } }, "components": { "schemas": { "BankAccountCredentials": { "title": "Bank Account Credentials", "description": "Result of generate credentials", "type": "object", "properties": { "username": { "type": "string", "example": "S0MW-TR0P-7DS0", "description": "Username used by the bank feeds platform to retrieve transactions" }, "password": { "type": "string", "example": "cO0ajh0uGyTN0Pwh", "description": "Password to enable the bank feeds platform to securely retrieve transactions." } }, "examples": [ { "QuickBooks Online Bank Feeds": null, "username": "S0MW-TR0P-7DS0", "password": "cO0ajh0uGyTN0Pwh" } ] }, "BankAccounts": { "x-internal": true, "title": "Accounting: Bank accounts", "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "title": "Accounting: Bank account", "description": "> **Accessing Bank Accounts through Banking API**\n> \n> This datatype was originally used for accessing bank account data both in accounting integrations and open banking aggregators. \n> \n> To view bank account data through the Banking API, please refer to the new [Banking: Account](https://docs.codat.io/bank-feeds-api#/schemas/Account) data type.\n\n## Overview\n\nA list of bank accounts associated with a company and a specific data connection.\n\nBank accounts data includes:\n* The name and ID of the account in the accounting software.\n* The currency and balance of the account.\n* The sort code and account number.", "type": "object", "allOf": [ { "properties": { "id": { "type": "string", "description": "Identifier for the account, unique for the company in the accounting software." } } }, { "$ref": "#/components/schemas/BankAccounts/allOf/0/properties/results/items/definitions/bankAccountPrototype" }, { "properties": { "metadata": { "title": "Metadata", "type": "object", "x-internal": true, "properties": { "isDeleted": { "type": "boolean", "description": "Indicates whether the record has been deleted in the third-party system this record originated from.", "nullable": true } } }, "supplementalData": { "title": "Supplemental data", "type": "object", "x-internal": true, "description": "Supplemental data is additional data you can include in our standard data types. \n\nIt is referenced as a configured dynamic key value pair that is unique to the accounting software. [Learn more](https://docs.codat.io/using-the-api/supplemental-data/overview) about supplemental data.", "properties": { "content": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "nullable": true } } } } }, { "title": "Modified dates", "x-internal": true, "allOf": [ { "title": "ModifiedDate", "x-internal": true, "type": "object", "properties": { "modifiedDate": { "allOf": [ { "$ref": "#/components/schemas/DateTime" }, { "description": "The date when the record was last fetched from the accounting software, commerce software, or open banking provider and updated in Codat’s data cache.\n\nUse it to identify and retrieve records that have changed since your last fetch. For example, filtering `modifiedDate` to today will provide new records updated in Codat today.\n\nThis date is populated for all data types except for attachments, balance sheets, company information, and profit & loss reports ([read more](https://docs.codat.io/using-the-api/modified-dates#modified-date)).\n\nIn Codat's data model, dates and times are represented using the ISO 8601 standard." } ] } } }, { "title": "Source Modified Date", "x-internal": true, "type": "object", "nullable": true, "properties": { "sourceModifiedDate": { "allOf": [ { "$ref": "#/components/schemas/DateTime" }, { "description": "The date when a record was last modified in the accounting software, 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 accounting software 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": { "bankAccountPrototype": { "title": "Bank account prototype", "type": "object", "properties": { "accountName": { "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." }, "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." }, "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.\n\nFreeAgent integrations\nFor Credit accounts, only the last four digits are required. For other types, the field is optional." }, "iBan": { "type": "string", "nullable": true, "description": "International bank account number of the account. Often used when making or receiving international payments." }, "currency": { "$ref": "#/components/schemas/SourceAccount/properties/currency", "description": "Base currency of the bank account." }, "balance": { "type": "number", "format": "decimal", "nullable": true, "description": "Balance of the bank account." }, "institution": { "type": "string", "nullable": true, "description": "The institution of the bank account." }, "availableBalance": { "type": "number", "format": "decimal", "nullable": true, "description": "Total available balance of the bank account as reported by the underlying data source. This may take into account overdrafts or pending transactions for example." }, "overdraftLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Pre-arranged overdraft limit of the account.\n\nThe value is always positive. For example, an overdraftLimit of `1000` means that the balance of the account can go down to `-1000`." }, "status": { "$ref": "#/components/schemas/BankAccounts/allOf/0/properties/results/items/definitions/bankAccountStatus" } } }, "bankAccountCreateResponse": { "title": "Create bank account response", "allOf": [ { "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/BankAccounts/allOf/0/properties/results/items" }, { "deprecated": true } ] } } }, { "$ref": "#/components/schemas/PushOperation" } ] }, "bankAccountRef": { "title": "Bank account reference", "type": "object", "properties": { "id": { "type": "string", "description": "Bank account 'id' for the account transaction." }, "name": { "type": "string", "description": "bank account 'name' for the account transaction." } }, "description": "Links to the Account transactions data type." }, "bankAccounts": { "title": "Accounting: Bank accounts", "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccounts/allOf/0/properties/results/items" } } } }, { "$ref": "#/components/schemas/Companies/allOf/1" } ] }, "bankAccountStatus": { "title": "Account status", "enum": [ "Unknown", "Active", "Archived", "Pending" ], "type": "string", "description": "Status of the bank account.", "example": "Active" } } } } } }, { "$ref": "#/components/schemas/Companies/allOf/1" } ] }, "BankFeedAccountMapping": { "title": "Bank feed account mapping", "type": "object", "additionalProperties": false, "properties": { "sourceAccountId": { "type": "string", "description": "Unique ID for the source account" }, "targetAccountId": { "type": "string", "nullable": true, "description": "Unique ID for the target account" }, "feedStartDate": { "$ref": "#/components/schemas/DateTime", "nullable": true, "description": "The date from which bank transactions can be provided to the platform." } }, "required": [ "sourceAccountId" ], "examples": [ { "sourceAccountId": "acc-002", "targetAccountId": "account-081" } ] }, "BankFeedAccountMappingResponse": { "title": "Bank feed account mapping response", "type": "object", "additionalProperties": false, "properties": { "sourceAccountId": { "type": "string", "description": "Unique ID for the source account." }, "targetAccountId": { "type": "string", "nullable": true, "description": "Unique ID for the target account." }, "status": { "type": "string", "nullable": true, "description": "Status of the POST request." }, "error": { "type": "string", "nullable": true, "description": "Error returned during the post request" } }, "examples": [ { "sourceAccountId": "acc-002", "targetAccountId": "account-081", "status": "Failed", "error": "A feed connection already exists to this account" } ] }, "BankFeedMapping": { "title": "Bank feed mapping", "type": "object", "additionalProperties": false, "properties": { "sourceAccountId": { "type": "string", "description": "Unique ID for the source account." }, "sourceAccountName": { "type": "string", "description": "Name for the source account." }, "sourceAccountNumber": { "type": "string", "description": "Account number for the source account." }, "sourceBalance": { "type": "number", "format": "decimal", "description": "Balance for the source account." }, "sourceCurrency": { "$ref": "#/components/schemas/SourceAccount/properties/currency" }, "targetAccountId": { "type": "string", "nullable": true, "description": "Unique ID for the target account in the accounting software." }, "targetAccountName": { "type": "string", "description": "Name for the target account in the accounting software." }, "status": { "type": "string", "description": "The status." }, "targetAccountOptions": { "type": "array", "nullable": true, "description": "An array of potential target accounts.", "items": { "$ref": "#/components/schemas/BankFeedMapping/definitions/targetAccountOption" } }, "feedStartDate": { "$ref": "#/components/schemas/DateTime", "nullable": true, "description": "The date from which bank transactions can be provided to the platform." } }, "description": "A bank feed connection between a source account and a target account, including potential target accounts.", "definitions": { "targetAccountOption": { "title": "Target Account Option", "type": "object", "properties": { "id": { "type": "string", "description": "Id of the target account." }, "name": { "type": "string", "nullable": true, "description": "Name of the target account." }, "balance": { "type": "number", "format": "decimal", "nullable": true, "description": "The balance of the account." }, "sortCode": { "type": "string", "nullable": true, "description": "The sort code of the account." }, "accountNumber": { "type": "string", "nullable": true, "description": "The account number of the account." } } }, "bankFeedMappings": { "title": "Bank feed mappings", "type": "array", "items": { "$ref": "#/components/schemas/BankFeedMapping" }, "additionalProperties": false } }, "examples": [ { "sourceAccountId": "acc-002", "targetAccountId": "account-081", "sourceCurrency": "USD", "status": "Success", "feedStartDate": "2023-01-09T14:14:14.1057478Z", "sourceAccountName": "ACME Bank", "sourceAccountNumber": "1234-5678", "sourceBalance": 500, "targetAccountName": "ACME Bank" }, { "sourceAccountId": "c53fd75a-dddb-4493-839a-5090b008f625", "status": "pending", "targetAccountOptions": [ { "name": "account-081", "id": "044096a7-1478-4554-8820-f478caad1b00", "balance": 100.99, "sortCode": "602336", "accountNumber": "23203" } ], "sourceAccountName": "bank name here", "sourceAccountNumber": "5670", "sourceBalance": 1550, "sourceCurrency": "GBP" } ] }, "BankTransactions": { "title": "Bank transactions", "type": "array", "maxItems": 1000, "items": { "title": "Bank transaction", "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for the bank account transaction, unique for the company in the accounting software.", "example": "716422529" }, "date": { "title": "Local date time", "type": "string", "examples": [ "2023-08-22T10:21:00", "2023-08-22" ], "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```\n2023-08-22T10:21:00\n2023-08-22\n```\n\nWhen pushing bank transaction data to Codat, the date is treated as a local date. This means:\n\n- The date/time is used exactly as provided, without any timezone conversion.\n- If a timezone offset is included (e.g., `2023-08-22T10:21:00-05:00`), the offset will be ignored and only the local date/time portion will be used.\n- We recommend providing dates without a timezone suffix for clarity (e.g., `2023-08-22T10:21:00` rather than `2023-08-22T10:21:00Z`)." }, "description": { "type": "string", "nullable": true, "description": "Description of the bank transaction.", "example": "Debit for Payment Id sdp-1-57379a43-c4b8-49f5-bd7c-699189ee7a60" }, "counterparty": { "type": "string", "nullable": true, "description": "The giving or receiving party such as a person or organization.", "example": "ACME INC" }, "reference": { "type": "string", "nullable": true, "description": "An optional reference to the bank transaction.", "example": "reference for transaction" }, "reconciled": { "type": "boolean", "nullable": true, "description": "`True` if the bank transaction has been [reconciled](https://www.xero.com/uk/guides/what-is-bank-reconciliation/) in the accounting software.", "example": false }, "amount": { "type": "number", "format": "decimal", "description": "The amount transacted in the bank transaction.", "example": 999.99 }, "balance": { "type": "number", "format": "decimal", "description": "The remaining balance in the account with ID `accountId`. This field is optional for QuickBooks Online but is required for Xero, Sage, NetSuite, Exact, and FreeAgent.", "example": -999.99 }, "transactionType": { "title": "Bank transaction type", "nullable": true, "description": "Type of transaction for the bank statement line.", "type": "string", "enum": [ "Unknown", "Credit", "Debit", "Int", "Div", "Fee", "SerChg", "Dep", "Atm", "Pos", "Xfer", "Check", "Payment", "Cash", "DirectDep", "DirectDebit", "RepeatPmt", "Other" ] } } } }, "ClientRateLimitWebhook": { "title": "Client rate limit webhook", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "description": "Unique identifier of the event." }, "eventType": { "type": "string", "description": "The type of event.", "examples": [ "client.rateLimit.reset", "client.rateLimit.reached" ] }, "generatedDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC the event was generated in Codat." }, "payload": { "$ref": "#/components/schemas/ClientRateLimitWebhook/definitions/clientRateLimitWebhookPayload" } }, "definitions": { "clientRateLimitWebhookPayload": { "title": "Client rate limit webhook payload", "type": "object", "properties": { "dailyQuota": { "type": "integer", "description": "The number of available requests per day." }, "quotaRemaining": { "type": "integer", "description": "Total number of requests remaining for your client." }, "expiryDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC when your daily quota is reset." } } } } }, "Companies": { "title": "Companies", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } }, { "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/Companies/allOf/1/definitions/links" } }, "definitions": { "links": { "title": "Hal Links", "type": "object", "required": [ "self", "current" ], "properties": { "self": { "$ref": "#/components/schemas/Companies/allOf/1/definitions/halRef" }, "current": { "$ref": "#/components/schemas/Companies/allOf/1/definitions/halRef" }, "next": { "$ref": "#/components/schemas/Companies/allOf/1/definitions/halRef" }, "previous": { "$ref": "#/components/schemas/Companies/allOf/1/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" } } } ] } ] }, "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/bank-feeds-api#/schemas/Connection) to different data sources such as one connection to [Xero](https://docs.codat.io/integrations/accounting/xero/accounting-xero) for accounting data, two connections to [Plaid](https://docs.codat.io/integrations/banking/plaid/banking-plaid) for two bank accounts and a connection to [Zettle](https://docs.codat.io/integrations/commerce/zettle/commerce-zettle) for POS data.\n\nTypically each company is one of your customers.\n\nWhen you create a company, you can specify a `name` and we will automatically generate a unique `id` for the company. You can also add a `description` to store any additional information about the company.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Company/definitions/companyDetails" }, { "type": "object", "properties": { "dataConnections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } } ], "definitions": { "companyDetails": { "title": "Company details", "type": "object", "properties": { "id": { "$ref": "#/components/parameters/companyId/schema" }, "name": { "type": "string", "description": "The name of the company", "example": "Codat Ltd." }, "description": { "$ref": "#/components/schemas/CompanyRequestBody/properties/description", "nullable": true }, "redirect": { "type": "string", "format": "uri", "description": "The `redirect` [Link URL](https://docs.codat.io/auth-flow/authorize-hosted-link) enabling the customer to start their auth flow journey for the company.", "example": "https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739" }, "lastSync": { "$ref": "#/components/schemas/DateTime", "nullable": true }, "created": { "$ref": "#/components/schemas/DateTime" }, "createdByUserName": { "type": "string", "description": "Name of user that created the company in Codat.", "nullable": true }, "products": { "type": "array", "items": { "type": "string" }, "description": "An array of products that are currently enabled for the company." }, "tags": { "title": "Tags", "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^.{1,27}$" }, "additionalProperties": { "type": "string", "maxLength": 100 }, "description": "A collection of user-defined key-value pairs that store custom metadata against the company." }, "referenceParentCompany": { "$ref": "#/components/schemas/Company/definitions/companyReference", "nullable": true, "description": "The parent entity or controlling organization of this company. Null if the company has no parent." }, "referenceSubsidiaryCompanies": { "type": "array", "nullable": false, "description": "A list of subsidiary companies owned or controlled by this entity. Empty if the company has no children.", "minItems": 0, "items": { "$ref": "#/components/schemas/Company/definitions/companyReference" } } }, "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" } ], "products": [ "spend-insights", "lending" ] } ] }, "CompanyAccessToken": { "title": "Company access token", "description": "Details of the access token provisioned for a company.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CompanyAccessToken/definitions/accessToken" } ], "definitions": { "accessToken": { "title": "Access token", "type": "object", "properties": { "expiresIn": { "type": "integer", "description": "The number of seconds until the access token expires.", "example": 86400 }, "accessToken": { "type": "string", "description": "The access token for the company." }, "tokenType": { "type": "string", "description": "The type of token.", "example": "Bearer" } }, "required": [ "expiresIn", "accessToken", "tokenType" ] } }, "examples": [ { "expiresIn": 86400, "accessToken": "string", "tokenType": "Bearer" } ] }, "CompanyInformation": { "title": "Company information", "description": "Information about the company from the underlying accounting software.", "type": "object", "properties": { "companyName": { "type": "string", "nullable": false, "description": "Name of the linked company." }, "baseCurrency": { "type": "string", "nullable": false, "description": "Currency set in the accounting software of the linked company." }, "planType": { "type": "string", "nullable": true, "description": "Accounting software subscription type such as Trial, Demo, Standard." }, "multicurrencyEnabled": { "type": "boolean", "description": "Boolean showing if the organisation has multicurrency enabled." }, "currencies": { "type": "array", "nullable": true, "description": "Array of enabled currencies for the linked company.", "items": { "type": "string" } } } }, "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" ] }, "CompanyUpdateRequest": { "title": "Update 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": { "$ref": "#/components/schemas/CompanyRequestBody/properties/description" }, "tags": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/tags" } } }, "Connection": { "title": "Connection", "description": "A connection represents a [company's](https://docs.codat.io/bank-feeds-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/DateTime", "nullable": true }, "created": { "$ref": "#/components/schemas/DateTime" }, "dataConnectionErrors": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Connection/definitions/dataConnectionError" } }, "connectionInfo": { "type": "object", "nullable": true, "additionalProperties": true } }, "additionalProperties": false, "required": [ "id", "integrationId", "integrationKey", "sourceId", "platformName", "linkUrl", "status", "created", "sourceType" ], "definitions": { "dataConnectionStatus": { "title": "Data connection status", "description": "The current authorization status of the data connection.", "type": "string", "enum": [ "PendingAuth", "Linked", "Unlinked", "Deauthorized" ] }, "dataConnectionError": { "title": "Data connection error", "type": "object", "properties": { "statusCode": { "type": "string", "description": "The HTTP status code returned by the source platform when the error occurred." }, "statusText": { "type": "string", "description": "A non-numeric status code/text returned by the source platform when the error occurred." }, "errorMessage": { "type": "string", "description": "A message about a error returned by Codat." }, "erroredOnUtc": { "$ref": "#/components/schemas/DateTime" }, "status": { "title": "Error status", "description": "The current status of a transient error. Null statuses indicate that the error is not transient.", "type": "string", "nullable": true, "enum": [ "Active", "Resolved" ] }, "resolvedOnUtc": { "description": "The datetime in Utc that the error was resolved.", "nullable": true, "$ref": "#/components/schemas/DateTime" } } }, "dataConnectionSourceType": { "title": "Source Type", "description": "The type of platform of the connection.", "type": "string", "enum": [ "Accounting", "Banking", "BankFeed", "Commerce", "Expense", "Other", "Unknown" ], "example": "Accounting" } }, "example": { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } }, "Connections": { "title": "Connections", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } }, { "$ref": "#/components/schemas/Companies/allOf/1" } ] }, "CreateBankTransactions": { "title": "Create bank transactions", "type": "object", "properties": { "accountId": { "type": "string", "description": "Unique identifier for a bank account.", "examples": [ "13d946f0-c5d5-42bc-b092-97ece17923ab", "9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2", "7110701885", "EILBDVJVNUAGVKRQ", "Checking 0202" ] }, "transactions": { "$ref": "#/components/schemas/BankTransactions" } }, "required": [ "accountId", "transactions" ] }, "CreateBankTransactionsResponse": { "title": "Create bank transaction response", "x-internal": true, "allOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateBankTransactions" } } }, { "$ref": "#/components/schemas/PushOperation" } ] }, "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" }, "DateTime": { "title": "Date time", "type": "string", "examples": [ "2022-10-23T00:00:00Z", "2022-10-23" ], "description": "In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example:\n\n```\n2020-10-08T22:40:50Z\n2021-01-01T00:00:00\n```\n\n\n\nWhen syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:\n\n- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`\n- Unqualified local time: `2021-11-15T01:00:00`\n- UTC time offsets: `2021-11-15T01:00:00-05:00`\n\n> Time zones\n> \n> Not all dates from Codat will contain information about time zones. \n> Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced." }, "ErrorMessage": { "title": "Error message", "type": "object", "x-internal": true, "properties": { "statusCode": { "type": "integer", "description": "The HTTP status code returned by the error." }, "service": { "type": "string", "description": "Codat's service the returned the error." }, "error": { "type": "string", "description": "A brief description of the error." }, "correlationId": { "type": "string", "description": "Unique identifier used to propagate to all downstream services and determine the source of the error." }, "validation": { "$ref": "#/components/schemas/ErrorMessage/definitions/errorValidation" }, "canBeRetried": { "type": "string", "description": "`True` if the error occurred transiently and can be retried." }, "detailedErrorCode": { "type": "integer", "description": "Machine readable error code used to automate processes based on the code returned." } }, "definitions": { "errorValidation": { "title": "Validation error", "type": "object", "nullable": true, "description": "A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.", "properties": { "errors": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ErrorMessage/definitions/errorValidationItem" } }, "warnings": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ErrorMessage/definitions/errorValidationItem" } } } }, "errorValidationItem": { "title": "Validation error item", "type": "object", "properties": { "itemId": { "type": "string", "nullable": true, "description": "Unique identifier for a validation item." }, "message": { "type": "string", "nullable": true, "description": "A message outlining validation item's issue." }, "validatorName": { "type": "string", "nullable": true, "description": "Name of validator." } } } } }, "PullOperation": { "title": "Pull operation", "description": "Information about a queued, in progress or completed pull operation.\n*Formally called `dataset`*", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the pull operation.", "example": "943accd0-4247-42d8-865b-363c8629e1da" }, "companyId": { "type": "string", "format": "uuid", "description": "Unique identifier of the company associated to this pull operation.", "example": "22ece347-e5f6-4896-95e0-35a4c7f17023" }, "connectionId": { "type": "string", "format": "uuid", "description": "Unique identifier of the connection associated to this pull operation.", "example": "50830828-7d39-4367-b0eb-5ddb2de5faa5" }, "dataType": { "title": "Data types", "x-internal": true, "type": "string", "description": "The data type you are requesting in a pull operation." }, "status": { "title": "Dataset status", "type": "string", "description": "The current status of the dataset.", "enum": [ "Initial", "Queued", "Fetching", "MapQueued", "Mapping", "Complete", "FetchError", "MapError", "InternalError", "ProcessingQueued", "Processing", "ProcessingError", "ValidationQueued", "Validating", "ValidationError", "AuthError", "Cancelled", "NotSupported", "RateLimitError", "PermissionsError", "PrerequisiteNotMet" ] }, "statusDescription": { "type": "string", "nullable": true, "description": "Additional information about the dataset status.", "example": "Paused until 2022-10-23T00:00:00.000Z" }, "errorMessage": { "type": "string", "nullable": true, "description": "A message about a transient or persistent error returned by Codat or the source platform." }, "requested": { "$ref": "#/components/schemas/DateTime" }, "completed": { "$ref": "#/components/schemas/DateTime" }, "progress": { "type": "integer", "description": "An integer signifying the progress of the pull operation." }, "isCompleted": { "type": "boolean", "description": "`True` if the pull operation is completed successfully. The `isCompleted` property is not queryable. To filter failed pull operations, query by `status!=Complete&&status!=NotSupported` instead." }, "isErrored": { "type": "boolean", "description": "`True` if the pull operation entered an error state." } }, "required": [ "id", "companyId", "connectionId", "dataType", "status", "requested", "progress", "isCompleted", "isErrored" ], "examples": [ { "id": "97d60846-f07a-4d42-b5a0-0bdcc6ebf56b", "companyId": "4645bd78-8988-45bc-ac9e-67ba5df6e4e5", "connectionId": "51baa045-4836-4317-a42e-3542e991e581", "dataType": "invoices", "status": "Initial", "statusDescription": "Paused until 2022-10-23T00:00:00.000Z", "requested": "2022-11-14T11:18:37.2798351Z", "progress": 10, "isCompleted": false, "isErrored": false } ] }, "PullOperations": { "title": "Pull operations", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PullOperation" } } } }, { "$ref": "#/components/schemas/Companies/allOf/1" } ] }, "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/DataType", "description": "The type of data being pushed, eg invoices, customers." }, "companyId": { "$ref": "#/components/parameters/companyId/schema" }, "pushOperationKey": { "type": "string", "format": "uuid", "description": "A unique identifier generated by Codat to represent this single push operation. This identifier can be used to track the status of the push, and should be persisted." }, "dataConnectionKey": { "$ref": "#/components/parameters/connectionId/schema" }, "requestedOnUtc": { "$ref": "#/components/schemas/DateTime", "description": "The datetime when the push was requested." }, "completedOnUtc": { "$ref": "#/components/schemas/DateTime", "description": "The datetime when the push was completed, null if Pending." }, "timeoutInMinutes": { "type": "integer", "format": "int32", "nullable": true, "description": "Number of minutes the push operation must complete within before it times out." }, "timeoutInSeconds": { "type": "integer", "format": "int32", "nullable": true, "deprecated": true, "description": "Number of seconds the push operation must complete within before it times out." }, "status": { "$ref": "#/components/schemas/PushOperation/definitions/pushOperationStatus" }, "errorMessage": { "type": "string", "nullable": true, "description": "A message about the error." }, "validation": { "$ref": "#/components/schemas/PushOperation/definitions/validation" }, "statusCode": { "type": "integer", "description": "Push status code." } }, "required": [ "companyId", "pushOperationKey", "dataConnectionKey", "requestedOnUtc", "status", "statusCode" ], "definitions": { "validation": { "type": "object", "title": "Validation", "description": "A human-readable object describing validation decisions Codat has made when pushing data into the platform. If a push has failed because of validation errors, they will be detailed here.", "properties": { "errors": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PushOperation/definitions/validationItem" } }, "warnings": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PushOperation/definitions/validationItem" } } } }, "validationItem": { "title": "Validation item", "type": "object", "properties": { "itemId": { "type": "string", "nullable": true, "description": "Unique identifier for a validation item." }, "message": { "type": "string", "nullable": true, "description": "A message outlining validation item's issue." }, "validatorName": { "type": "string", "nullable": true, "description": "Name of validator." } }, "additionalProperties": false }, "pushChangeType": { "title": "Push change type", "description": "Type of change being applied to record in third party platform.", "type": "string", "enum": [ "Unknown", "Created", "Modified", "Deleted", "AttachmentUploaded" ] }, "pushOperationRef": { "title": "Push operation reference", "x-internal": true, "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for a push operation." }, "dataType": { "$ref": "#/components/schemas/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/Companies/allOf/1" } ] }, "PushOption": { "title": "Push option", "x-internal": true, "required": [ "displayName", "required", "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionType" }, "displayName": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/displayName" }, "description": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/description" }, "required": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/required" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty" }, "nullable": true }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionChoice" }, "nullable": true }, "validation": { "$ref": "#/components/schemas/PushOption/definitions/pushValidationInfo", "nullable": true } }, "definitions": { "pushOptionProperty": { "title": "Push Option Property", "required": [ "description", "displayName", "required", "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionType" }, "displayName": { "minLength": 1, "type": "string", "description": "The property's display name." }, "description": { "type": "string", "description": "A description of the property." }, "required": { "type": "boolean", "description": "The property is required if `True`." }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty" }, "nullable": true }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionChoice" }, "nullable": true }, "validation": { "$ref": "#/components/schemas/PushOption/definitions/pushValidationInfo" } } }, "pushValidationInfo": { "title": "Push validation info", "type": "object", "properties": { "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PushOption/definitions/pushFieldValidation" }, "nullable": true }, "information": { "type": "array", "items": { "$ref": "#/components/schemas/PushOption/definitions/pushFieldValidation" }, "nullable": true } }, "additionalProperties": false }, "pushFieldValidation": { "title": "Push field validation", "required": [ "details" ], "type": "object", "properties": { "field": { "type": "string", "description": "Field name that resulted in the validation issue." }, "details": { "minLength": 1, "type": "string", "description": "Details on the validation issue." }, "ref": { "type": "string", "format": "uri", "nullable": true, "description": "Unique reference identifier for the validation issue." } }, "additionalProperties": false }, "pushOptionType": { "title": "Option Type", "description": "The option type.", "enum": [ "Array", "Object", "String", "Number", "Boolean", "DateTime", "File", "MultiPart" ], "type": "string" }, "pushOptionChoice": { "title": "Push Option Choice", "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Allowed value for field." }, "type": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionType" }, "displayName": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/displayName" }, "description": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/description" }, "required": { "$ref": "#/components/schemas/PushOption/definitions/pushOptionProperty/properties/required" } } } } }, "SourceAccount": { "title": "Source account (v1)", "type": "object", "description": "The target bank account in a supported accounting software for ingestion into a bank feed.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique ID for the bank account." }, "accountName": { "type": "string", "nullable": true, "description": "The bank account name." }, "accountType": { "type": "string", "nullable": true, "description": "The type of bank account e.g. Credit." }, "accountNumber": { "type": "string", "nullable": true, "description": "The account number." }, "sortCode": { "type": "string", "nullable": true, "description": "The sort code." }, "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" ] }, "balance": { "type": "number", "format": "decimal", "nullable": true, "description": "The latest balance for the bank account." }, "modifiedDate": { "$ref": "#/components/schemas/DateTime", "nullable": true, "description": "The last date the bank account was modified." }, "status": { "type": "string", "nullable": true, "description": "Status of the source account.", "enum": [ "pending", "connected", "connecting", "disconnected", "unknown" ] }, "feedStartDate": { "$ref": "#/components/schemas/DateTime", "nullable": true } }, "required": [ "id" ], "definitions": { "sourceAccountPrototype": { "title": "Source account (v1)", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/SourceAccount/properties/id" }, "accountName": { "$ref": "#/components/schemas/SourceAccount/properties/accountName" }, "accountType": { "$ref": "#/components/schemas/SourceAccount/properties/accountType" }, "accountNumber": { "$ref": "#/components/schemas/SourceAccount/properties/accountNumber" }, "sortCode": { "$ref": "#/components/schemas/SourceAccount/properties/sortCode" }, "currency": { "$ref": "#/components/schemas/SourceAccount/properties/currency" }, "balance": { "$ref": "#/components/schemas/SourceAccount/properties/balance" }, "modifiedDate": { "$ref": "#/components/schemas/SourceAccount/properties/modifiedDate" } }, "required": [ "id" ] }, "sourceAccounts": { "title": "Source accounts", "type": "array", "items": { "$ref": "#/components/schemas/SourceAccount" } } }, "examples": [ { "id": "acc-002", "accountName": "account-081", "sortCode": "123456", "accountType": "Credit", "accountNumber": "12345670", "currency": "GBP", "balance": 99.99, "modifiedDate": "2023-01-09T14:14:14.1057478Z", "status": "pending" }, { "id": "acc-003", "accountName": "account-095", "sortCode": "123456", "accountType": "Credit", "accountNumber": "12345671", "currency": "USD", "balance": 0, "modifiedDate": "2023-01-09T14:14:14.1057478Z", "status": "pending" } ] }, "SourceAccountBatchCreateResponse": { "title": "Batch source account request creation response", "description": "Account ID and resulting object of the batch `Create source account` request.", "type": "object", "properties": { "sourceAccountId": { "type": "string", "description": "Unique ID for the source account.", "examples": [ "12345" ] }, "result": { "$ref": "#/components/schemas/SourceAccountBatchCreateResponse/definitions/sourceAccountBatchCreateResult" } }, "definitions": { "sourceAccountBatchCreateResult": { "title": "Source Account Batch Create Result", "description": "Status details and corresponding object of the `Create account` operation.", "type": "object", "properties": { "statusCode": { "type": "integer", "description": "The HTTP status code for the creation of the source account" }, "error": { "type": "string", "nullable": true, "description": "A brief description of the error." }, "account": { "$ref": "#/components/schemas/SourceAccount" } } } } }, "SourceAccountBatchErrorResponse": { "title": "Batch source account creation error", "description": "Describes the error that occured when trying to create the specified source account.", "type": "object", "properties": { "sourceAccountId": { "type": "string", "description": "Unique ID for the source account.", "examples": [ "12345" ] }, "result": { "type": "object", "properties": { "statusCode": { "description": "The error status code for the attempted creation of the source account.", "type": "string", "examples": [ 409 ] }, "error": { "description": "The error description for the attempted creation of the source account.", "type": "string", "examples": [ "A bank account already exists with the same Id" ] } } } } }, "SourceAccountV2": { "title": "Source account (v2)", "type": "object", "description": "The target bank account in a supported accounting software for ingestion into a bank feed.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique ID for the bank account." }, "accountName": { "type": "string", "description": "The bank account name." }, "accountType": { "type": "string", "description": "The type of bank account e.g. checking, savings, loan, creditCard, prepaidCard.", "enum": [ "checking", "savings", "loan", "creditCard", "prepaidCard" ] }, "accountNumber": { "type": "string", "description": "The account number." }, "sortCode": { "type": "string", "nullable": true, "description": "The sort code." }, "routingInfo": { "$ref": "#/components/schemas/SourceAccountV2/definitions/routingInfo" }, "currency": { "$ref": "#/components/schemas/SourceAccount/properties/currency" }, "balance": { "type": "number", "format": "decimal", "description": "The latest balance for the bank account." }, "accountInfo": { "$ref": "#/components/schemas/SourceAccountV2/definitions/accountInfo" }, "modifiedDate": { "$ref": "#/components/schemas/DateTime", "nullable": true, "description": "The last date the bank account was modified." }, "status": { "type": "string", "nullable": true, "description": "Status of the source account.", "enum": [ "pending", "connected", "connecting", "disconnected", "unknown" ] }, "feedStartDate": { "nullable": true, "title": "Date", "type": "string", "example": "2022-10-23", "description": "In Codat's data model, dates are represented using the ISO 8601 standard. Date fields are formatted as strings; for example:\n```\n2020-10-08\n```" } }, "required": [ "id", "accountName", "accountType", "accountNumber", "currency", "balance" ], "definitions": { "sourceAccountV2Prototype": { "title": "Source account (v2)", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/SourceAccountV2/properties/id" }, "accountName": { "$ref": "#/components/schemas/SourceAccountV2/properties/accountName" }, "accountType": { "$ref": "#/components/schemas/SourceAccountV2/properties/accountType" }, "accountNumber": { "$ref": "#/components/schemas/SourceAccountV2/properties/accountNumber" }, "routingInfo": { "$ref": "#/components/schemas/SourceAccountV2/definitions/routingInfo" }, "sortCode": { "$ref": "#/components/schemas/SourceAccountV2/properties/sortCode" }, "currency": { "$ref": "#/components/schemas/SourceAccount/properties/currency" }, "balance": { "$ref": "#/components/schemas/SourceAccountV2/properties/balance" }, "modifiedDate": { "$ref": "#/components/schemas/SourceAccountV2/properties/modifiedDate" }, "accountInfo": { "$ref": "#/components/schemas/SourceAccountV2/definitions/accountInfo" } }, "required": [ "id", "accountName", "accountType", "accountNumber", "currency", "balance" ] }, "accountInfo": { "title": "Account Info", "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "Description of the account." }, "nickname": { "type": "string", "nullable": true, "description": "Name given to the account by the user. Used in UIs to assist in account selection." }, "accountOpenDate": { "$ref": "#/components/schemas/SourceAccountV2/properties/feedStartDate", "nullable": true, "description": "Date when the account was opened or created at the provider" }, "availableBalance": { "type": "number", "format": "decimal", "nullable": true, "description": "Balance of funds available for use. This includes pending activity." } } }, "sourceAccounts": { "title": "Source accounts", "type": "array", "items": { "$ref": "#/components/schemas/SourceAccountV2" } }, "routingInfo": { "title": "Routing Info", "type": "object", "description": "Routing information for the bank. This does not include account number.", "properties": { "bankCode": { "type": "string", "nullable": true, "description": "The numeric identifier of the routing number" }, "type": { "type": "string", "nullable": true, "default": "bankcode", "enum": [ "rtn", "aba", "swift", "bsb", "iban", "nz2", "trno", "sortcode", "blz", "ifsc", "bankcode", "apca", "clabe" ], "description": "The type of routing number." } } } }, "examples": [ { "id": "acc-001", "accountName": "account-081", "accountType": "checking", "accountNumber": "12345670", "routingInfo": { "bankCode": "021001088", "type": "bankcode" }, "currency": "GBP", "balance": 99.99, "accountInfo": { "description": "account description 1", "nickname": "account 123", "accountOpenDate": "2023-05-06", "availableBalance": 10 }, "modifiedDate": "2024-08-02T00:00:00.000Z", "status": "pending", "feedStartDate": "2024-05-01" }, { "id": "acc-002", "accountName": "account-083", "accountType": "savings", "accountNumber": "23456789", "routingInfo": { "bankCode": "021001088", "type": "bankcode" }, "currency": "GBP", "balance": 400, "accountInfo": { "description": "account description 2", "nickname": "account 1290", "accountOpenDate": "2023-05-23", "availableBalance": 400 }, "modifiedDate": "2024-08-02T00:00:00.000Z", "status": "pending", "feedStartDate": "2024-05-01" } ] }, "SourceAccountV2BatchCreateResponse": { "title": "Batch source account (v2) creation response", "description": "Account ID and resulting object of the batch `Create source account` request.", "type": "object", "properties": { "sourceAccountId": { "type": "string", "description": "Unique ID for the source account.", "examples": [ "12345" ] }, "result": { "$ref": "#/components/schemas/SourceAccountV2BatchCreateResponse/definitions/sourceAccountV2BatchCreateResult" } }, "definitions": { "sourceAccountV2BatchCreateResult": { "title": "Source Account V2 Batch CreateResult", "description": "Status details and corresponding object of the `Create account` operation.", "type": "object", "properties": { "statusCode": { "type": "integer", "description": "The HTTP status code for the creation of the source account" }, "error": { "type": "string", "nullable": true, "description": "A brief description of the error." }, "account": { "$ref": "#/components/schemas/SourceAccountV2" } } } } }, "SourceAccountWebhook": { "title": "Source account status changed webhook", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "ba29118f-5406-4e59-b05c-ba307ca38d01", "description": "Unique identifier of the event." }, "eventType": { "type": "string", "description": "The type of event.", "examples": [ "bankFeeds.sourceAccount.connected", "bankFeeds.sourceAccount.disconnected" ] }, "generatedDate": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC the event was generated in Codat." }, "payload": { "$ref": "#/components/schemas/SourceAccountWebhook/definitions/sourceAccountWebhookPayload" } }, "definitions": { "sourceAccountWebhookPayload": { "title": "Payload", "type": "object", "properties": { "referenceCompany": { "$ref": "#/components/schemas/Company/definitions/companyReference" }, "companyId": { "$ref": "#/components/parameters/companyId/schema", "deprecated": true }, "connectionId": { "$ref": "#/components/parameters/connectionId/schema" }, "sourceAccount": { "oneOf": [ { "$ref": "#/components/schemas/SourceAccountV2" }, { "$ref": "#/components/schemas/SourceAccount" } ] } } } } }, "StartScheduledSyncResult": { "title": "Start scheduled sync result", "type": "object", "description": "Represents the result of an ad-hoc sync request.", "properties": { "syncId": { "type": "string", "format": "uuid", "description": "The unique identifier for the created sync." } }, "required": [ "syncId" ] }, "SyncStatusResult": { "title": "Sync status", "type": "object", "description": "Represents the status of a managed bank feed sync.", "properties": { "syncId": { "type": "string", "format": "uuid", "description": "The unique identifier for the sync." }, "clientId": { "type": "string", "format": "uuid", "description": "The ID of the client associated with the company that owns the source bank account." }, "companyId": { "type": "string", "format": "uuid", "description": "The ID of the company that owns the source bank account." }, "companyName": { "type": "string", "description": "The name of the company that owns the source bank account." }, "dataConnectionId": { "type": "string", "format": "uuid", "description": "The ID of the target accounting data connection." }, "sourceAccountId": { "type": "string", "description": "The ID of the source bank account from which transactions are fetched." }, "periodStartUtc": { "type": "string", "format": "date-time", "description": "The start of the sync period." }, "periodEndUtc": { "type": "string", "format": "date-time", "description": "The end of the sync period." }, "executionStartUtc": { "type": "string", "format": "date-time", "description": "The UTC timestamp when the sync started executing." }, "status": { "type": "string", "description": "The current status of the sync. Known values are `Started`, `Failed`, `SuccessDataPushed`, `SuccessNoDataPushed`, `PartialSuccessDataPushed`.", "example": "SuccessDataPushed" }, "executionEndUtc": { "type": "string", "format": "date-time", "nullable": true, "description": "The UTC timestamp when the sync execution ended, if completed (i.e. `status` is any value other than `Started`)." }, "errorMessage": { "type": "string", "nullable": true, "description": "Error message if the sync failed." }, "errorCode": { "type": "string", "nullable": true, "description": "Error code if the sync failed." }, "pushOperationKeys": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true, "description": "List of write operation keys associated with the sync, if the sync resulted in write attempts." } }, "required": [ "syncId", "clientId", "companyId", "companyName", "dataConnectionId", "sourceAccountId", "periodStartUtc", "periodEndUtc", "executionStartUtc", "status" ] } }, "parameters": { "companyId": { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "8a210b68-6988-11ed-a1eb-0242ac120002", "description": "Unique identifier for your SMB in Codat." }, "description": "Unique identifier for a company." }, "connectionId": { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "2e9d2c44-f675-40ba-8049-353bfcb5e171", "description": "Unique identifier for a company's data connection." }, "description": "Unique identifier for a connection." }, "accountId": { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "13d946f0-c5d5-42bc-b092-97ece17923ab", "9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2", 7110701885, "EILBDVJVNUAGVKRQ" ] }, "description": "Unique identifier for an account." }, "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)." }, "dataType": { "name": "dataType", "description": "The key of a Codat data type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DataType" } }, "datasetId": { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Unique identifier for the dataset that completed its sync." }, "description": "Unique identifier for the dataset that completed its sync." }, "timeoutInMinutes": { "name": "timeoutInMinutes", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "Time limit for the push operation to complete before it is timed out." } }, "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 } } } } } }, "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/platform-api#/schemas/ApiKeyDetails) 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/platform-api#/operations/list-api-keys), 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)" } } } }