{ "openapi": "3.1.0", "servers": [ { "description": "Production", "url": "https://api.codat.io" } ], "info": { "title": "Bank Feeds API", "version": "3.0.0", "contact": { "email": "support@codat.io", "name": "Codat" }, "description": "Bank Feeds API 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 product](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": "Configuration", "description": "Configure bank feeds 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": "Sync", "description": "Monitor the status of data syncs." }, { "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." } ], "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" } }, "With a description": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Technicalium", "description": "Technology services, including web and app design and development", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18.1950523Z", "createdByUserName": "Dan Tzabar" } }, "With a tag": { "value": { "id": "ab12c58d-a678-4ebf-a159-ae99e1807bd0", "name": "Technicalium", "description": "", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18.1950523Z", "createdByUserName": "Dan Tzabar", "tags": { "region": "us" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } }, "description": "Use the *Create company* endpoint to create a new [company](https://docs.codat.io/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" } ], "pageNumber": 1, "pageSize": 100, "totalResults": 1, "_links": { "current": { "href": "/companies?page=1&pageSize=100" }, "self": { "href": "/companies" } } } }, "List of Companies": { "value": { "results": [ { "id": "d1568dde-adf6-11ed-afa1-0242ac120002", "name": "Technicalium", "description": "Technology services, including web and app design and development", "platform": "", "redirect": "https://link.codat.io/company/d1568dde-adf6-11ed-afa1-0242ac120002", "lastSync": "2022-01-01T12:30:00.000Z", "dataConnections": [ { "id": "51baa045-4836-4317-a42e-3542e991e581", "integrationId": "1c312d69-e638-46d4-ad31-72e6c3ba8390", "integrationKey": "vjms", "sourceId": "396c3158-5dd7-481b-a7c4-a795ca31792b", "platformName": "Pandle", "linkUrl": "https://link-api.codat.io/companies/d1568dde-adf6-11ed-afa1-0242ac120002/connections/51baa045-4836-4317-a42e-3542e991e581/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-01-01T11:30:00Z", "createdByUserName": "Joe Bloggs" }, { "id": "096db70b-78de-4ff0-aa98-299cb5fe17a0", "name": "Godata", "description": "A new digital agency with a passion for creating amazing digital experiences", "platform": "", "redirect": "https://link.codat.io/company/096db70b-78de-4ff0-aa98-299cb5fe17a0", "lastSync": "2022-01-01T12:30:00.000Z", "dataConnections": [ { "id": "a70bc148-dc21-46b2-a257-d9c58ac15cbb", "integrationId": "1c312d69-e638-46d4-ad31-72e6c3ba8390", "integrationKey": "vjms", "sourceId": "396c3158-5dd7-481b-a7c4-a795ca31792b", "platformName": "Pandle", "linkUrl": "https://link-api.codat.io/companies/096db70b-78de-4ff0-aa98-299cb5fe17a0/connections/a70bc148-dc21-46b2-a257-d9c58ac15cbb/start", "status": "Linked", "lastSync": "2022-01-01T12:30:00.000Z", "created": "2022-01-01T11:30:00Z", "sourceType": "Accounting" } ], "created": "2022-01-01T11:30:00Z", "createdByUserName": "Mike Smith" } ], "pageNumber": 1, "pageSize": 100, "totalResults": 2, "_links": { "current": { "href": "/companies?page=1&pageSize=100" }, "self": { "href": "/companies" } } } } } } } }, "400": { "$ref": "#/components/responses/Malformed-Query" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } }, "operationId": "list-companies", "description": "The *List companies* endpoint returns a list of [companies] associated to your instances.\n\nA [company](https://docs.codat.io/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.", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ] } }, "/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": "My First Company", "description": "", "platform": "", "redirect": "https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0", "dataConnections": [], "created": "2022-11-10T10:45:18Z", "createdByUserName": "Dan Tzabar" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } } }, "delete": { "summary": "Delete a company", "operationId": "delete-company", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "description": "The *Delete company* endpoint permanently deletes a [company](https://docs.codat.io/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": "Update company", "description": "Use the *Update company* endpoint to update both the name and description of the company. \n\nA [company](https://docs.codat.io/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": "update-company", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "tags": [ "Companies" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/Payment-Required" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/Not-Found" }, "429": { "$ref": "#/components/responses/Too-Many-Requests" }, "500": { "$ref": "#/components/responses/Internal-Server-Error" }, "503": { "$ref": "#/components/responses/Service-Unavailable" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRequestBody" }, "examples": { "Update name": { "value": { "name": "New Name" } }, "Update description": { "value": { "name": "Same name", "description": "Additional documents required" } } } } } } } }, "/companies/{companyId}/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/bank-feeds-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}/sync/banking/config": { "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "get": { "summary": "Get configuration", "operationId": "get-configuration", "x-internal": true, "tags": [ "Configuration" ], "description": "The *Get configuration* endpoint returns the current configuration for a given company ID.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Configuration" }, "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" } } }, "post": { "summary": "Set configuration", "operationId": "set-configuration", "x-speakeasy-name-override": "set", "x-internal": true, "tags": [ "Configuration" ], "description": "Use *Set configuration* endpoint to configure a given company ID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Configuration" }, "examples": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Configuration" }, "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}/sync/banking/syncs/lastSuccessful/status": { "get": { "tags": [ "Sync" ], "description": "Use the _Get last successful sync_ endpoint to obtain the status information for the company's [most recent successful sync](https://docs.codat.io/bank-feeds-api#/schemas/CompanySyncStatus). ", "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySyncStatus" }, "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" } }, "summary": "Get last successful sync", "operationId": "get-last-successful", "x-speakeasy-name-override": "get-last-successful-sync", "x-internal": true } }, "/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 behaviour**\r\n\r\nSee the *response examples* for integration-specific indicative models.\r\n\r\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=bankAccounts) for integrations that support creating and updating a bank account.\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 behaviour**\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).\r\n\r\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=bankAccounts) for integrations that support creating an account.", "operationId": "create-bank-account" } }, "/companies/{companyId}/connections/{connectionId}/connectionInfo/bankFeedAccounts": { "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ], "post": { "tags": [ "Source accounts" ], "summary": "Create 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#### 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 behaviour\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 | | | ✅ |\n\n> ### Versioning\n> If you are integrating the Bank Feeds API 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" }, { "$ref": "#/components/schemas/SourceAccount" } ] }, "examples": {} } } }, "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 API 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 only updates the `accountName` field.\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.", "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", "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 behaviour**\n\nRequired data may vary by integration. To see what data to post, first call [Get create bank transaction model](https://docs.codat.io/bank-feeds-api#/operations/get-create-bankTransactions-model).\n\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=bankTransactions) for integrations that support creating a bank account transactions.\n", "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:00Z", "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:00Z", "description": "Amazon Purchase", "counterparty": "Amazon", "reference": "Ref-12346", "reconciled": false, "amount": -100, "balance": 0, "transactionType": "Debit" }, { "id": "716422531", "date": "2023-08-22T10:23:00Z", "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:00Z", "description": "Repayment of Credit Card", "amount": 100, "balance": 100, "transactionType": "Credit" }, { "id": "716422530", "date": "2023-08-22T10:22:00Z", "description": "Amazon Purchase", "amount": -100, "balance": 0, "transactionType": "Debit" }, { "id": "716422531", "date": "2023-08-22T10:23:00Z", "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:00Z", "description": "Repayment of Credit Card", "amount": 100, "transactionType": "Credit" }, { "id": "716422530", "date": "2023-08-22T10:22:00Z", "description": "Amazon Purchase", "amount": -100, "transactionType": "Debit" }, { "id": "716422531", "date": "2023-08-22T10:23:00Z", "description": "Office Supplies", "amount": -60, "transactionType": "Debit" } ] } }, "Sage": { "value": { "accountId": "49cd5a42-b311-4750-9361-52e2ed1d4653", "transactions": [ { "id": "716422529", "date": "2023-08-22T10:21:00Z", "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:00Z", "description": "Amazon Purchase", "counterparty": "Amazon", "reference": "Ref-12346", "amount": -100, "balance": 0, "transactionType": "Debit" }, { "id": "716422531", "date": "2023-08-22T10:23:00Z", "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}/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" } } } } }, "webhooks": { "client.rateLimit.reached": { "post": { "description": "Called when your client’s request count to Codat's API surpasses the allocated quota.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRateLimitWebhook" }, "examples": { "Reached": { "value": { "id": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "eventType": "client.rateLimit.reached", "generatedDate": "2024-09-01T00:00:00Z", "payload": { "dailyQuota": 12000, "quotaRemaining": 0, "expiryDate": "2024-09-01T12:14:14Z" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "client.rateLimit.reset": { "post": { "description": "Called when your client's rate limit quota is reset, allowing additional requests to Codat's API.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRateLimitWebhook" }, "examples": { "Reset": { "value": { "id": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "eventType": "client.rateLimit.reset", "generatedDate": "2024-09-01T00:00:00Z", "payload": { "dailyQuota": 12000, "quotaRemaining": 11993, "expiryDate": "2024-09-01T23:59:99Z" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Client rate limit reached": { "post": { "deprecated": true, "description": "Called when your client’s requests to Codat's API exceed the allocated quota. \n\n**Note: This event type is deprecated. Developers should now use the `client.rateLimit.reached` event for handling rate limit notifications.**", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRateLimitReachedWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "Client rate limit reset": { "post": { "deprecated": true, "description": "Called when the rate limit quota has reset for the client, and more requests to Codat's API are available.\n\nNote: This event type is deprecated. Developers should now use the `client.rateLimit.reset` event for handling rate limit notifications.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully." } } } }, "bankFeeds.sourceAccount.connected": { "post": { "description": "Called when a bank feed source account has become connected.", "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.105Z", "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.", "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.105Z", "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": { "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 datatype [here](https://docs.codat.io/bank-feeds-api#/schemas/Account)\n\n> View the coverage for bank accounts in the Data coverage explorer.\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 data source and updated in Codat’s data cache. \n\nUse it to identify and retrieve records that have changed since your last fetch. For example, filtering `modifiedDate` to today will provide new records updated in Codat today.\n\nThis date is populated for all data types except for attachments, balance sheets, company information, and profit & loss reports ([read more](https://docs.codat.io/using-the-api/modified-dates#modified-date)).\n\nIn Codat's data model, dates and times are represented using the ISO 8601 standard." } ] } } }, { "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 source platform, usually by the business or a business process. For example, when payments are made against an invoice. \n\nIt is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when:\n - Pulling attachments\n - The integration platform does not provide modification dates for a data type\n - A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred\n - A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records\n\nIn Codat's data model, dates and times are represented using the ISO 8601 standard." } ] } } } ] } ], "definitions": { "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" } }, "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": "string", "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": { "$ref": "#/components/schemas/DateTime" }, "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" ] } }, "required": [ "id", "date", "amount" ] } }, "ClientRateLimitReachedWebhook": { "title": "Client rate limit reached webhook", "x-internal": true, "description": "Webhook request body for a client that has reached their rate limit.", "type": "object", "properties": { "ClientId": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/ClientId" }, "ClientName": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/ClientName" }, "RuleId": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/RuleId" }, "RuleType": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/RuleType" }, "AlertId": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/AlertId" }, "Message": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/properties/Message" }, "Data": { "$ref": "#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData" } }, "definitions": { "ClientRateLimitReachedWebhookData": { "type": "object", "title": "Client rate limit reached webhook data", "properties": { "DailyQuota": { "type": "integer", "description": "The number of available requests per day." }, "ExpiresUtc": { "$ref": "#/components/schemas/DateTime", "description": "The date time in UTC when your daily quota is reset." } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Rate Limit Reached", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "The current daily rate limit quota of 1000 requests for bae71d36-ff47-420a-b4a6-f8c9ddf41140 has been reached.", "Data": { "DailyQuota": 1000, "ExpiresUtc": "2023-05-03T00:00:00Z" } } ] }, "ClientRateLimitResetWebhook": { "title": "Client rate limit reset webhook", "x-internal": true, "description": "Webhook request body for a client that has had their rate limit reset.", "type": "object", "properties": { "ClientId": { "title": "Client ID", "type": "string", "format": "uuid", "description": "Unique identifier for your client in Codat." }, "ClientName": { "type": "string", "description": "Name of your client in Codat." }, "RuleId": { "type": "string", "format": "uuid", "description": "Unique identifier for the rule.", "deprecated": true }, "RuleType": { "type": "string", "x-stoplight": { "id": "34d52a089f08a" }, "description": "The type of rule." }, "AlertId": { "type": "string", "format": "uuid", "description": "Unique identifier of the webhook event." }, "Message": { "type": "string", "description": "A human-readable message about the webhook." }, "Data": { "$ref": "#/components/schemas/ClientRateLimitResetWebhook/definitions/ClientRateLimitResetWebhookData" } }, "definitions": { "ClientRateLimitResetWebhookData": { "type": "object", "title": "Client rate limit reset webhook data", "properties": { "QuotaRemaining": { "type": "integer", "description": "Total number of requests remaining for your client.", "nullable": true }, "ResetReason": { "type": "string", "description": "The reason for your rate limit quota being reset." }, "DailyQuota": { "$ref": "#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/DailyQuota", "nullable": true }, "ExpiresUtc": { "$ref": "#/components/schemas/ClientRateLimitReachedWebhook/definitions/ClientRateLimitReachedWebhookData/properties/ExpiresUtc", "nullable": true } } } }, "examples": [ { "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140", "ClientName": "Bank of Dave", "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac", "RuleType": "Rate Limit Reset", "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e", "Message": "The current daily rate limit quota for client 30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e has been reset to 1000 requests.", "Data": { "QuotaRemaining": 1000, "ResetReason": "The quota was reset because it is a new day.", "DailyQuota": 1000, "ExpiresUtc": "2023-05-03T00:00:00Z" } } ] }, "ClientRateLimitWebhook": { "title": "Client rate limit webhook", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "743ec94a-8aa4-44bb-8bd4-e1855ee0e74b", "description": "Unique identifier of the event." }, "eventType": { "type": "string", "description": "The type of event.", "examples": [ "client.rateLimit.reset", "client.rateLimit.reached" ] }, "generatedDate": { "$ref": "#/components/schemas/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": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^.{1,27}$" }, "additional properties": { "type": "string", "maxLength": 100 }, "description": "A collection of user-defined key-value pairs that store custom metadata against the company." } }, "required": [ "id", "name", "redirect" ] }, "companyReference": { "title": "Company reference", "type": "object", "properties": { "id": { "$ref": "#/components/parameters/companyId/schema" }, "name": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/name" }, "description": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/description" }, "links": { "type": "object", "description": "A collection of links for the company.", "properties": { "portal": { "type": "string", "format": "uri", "description": "Link to the company page in the portal." } } }, "tags": { "$ref": "#/components/schemas/Company/definitions/companyDetails/properties/tags" } } } }, "examples": [ { "id": "0498e921-9b53-4396-a412-4f2f5983b0a2", "name": "string", "redirect": "https://link.codat.io/company/27628208-459c-46a2-a705-5641ce25f739", "lastSync": "2022-01-01T12:00:00.000Z", "created": "2022-01-01T12:00:00.000Z", "createdByUserName": "string", "tags": { "region": "us", "uid": "f6b0c253-16c7-4da1-a0c5-9c871e9c9d6c" }, "dataConnections": [ { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } ] } ] }, "CompanyInformation": { "title": "Company information", "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", "nullable": true, "description": "Boolean showing if the organisation has multicurrency enabled" } } }, "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" ] }, "CompanySyncStatus": { "title": "Company sync status", "type": "object", "additionalProperties": false, "x-examples": { "Success Data Pushed": { "companyId": "20803807-4e9a-4cb7-b67b-9f889a3916e1", "syncId": "aa4c9dfd-e945-4424-9628-9e724f14c267", "syncStatusCode": 2000, "syncStatus": "Complete", "errorMessage": "", "syncExceptionMessage": "", "syncUtc": "2023-01-24T14:15:22Z", "dataPushed": true }, "Success No Data Pushed": { "companyId": "20803807-4e9a-4cb7-b67b-9f889a3916e1", "syncId": "aa4c9dfd-e945-4424-9628-9e724f14c267", "syncStatusCode": 2040, "syncStatus": "Complete", "errorMessage": "", "syncExceptionMessage": "", "syncUtc": "2023-01-24T14:15:22Z", "dataPushed": false } }, "properties": { "companyId": { "type": "string", "description": "Unique identifier for your SMB in Codat.", "example": "d4d73051-ed31-42b6-99f6-d288cd940992", "nullable": true }, "syncId": { "type": "string", "description": "Unique identifier of the sync.", "example": "a6a22aff-a43a-411d-a910-2dae73217cce", "nullable": true }, "syncStatusCode": { "type": "integer", "format": "int32", "description": "Status code of the sync.", "example": 2000 }, "syncStatus": { "type": "string", "description": "Text status of the sync.", "examples": [ "Complete", "PushError", "Started", "NotStarted", "Pushing" ], "nullable": true }, "errorMessage": { "type": "string", "description": "Error message of the sync.", "nullable": true }, "syncExceptionMessage": { "type": "string", "description": "Exception message of the sync.", "nullable": true }, "syncUtc": { "$ref": "#/components/schemas/DateTime", "description": "Datetime of the sync.", "nullable": true }, "dataPushed": { "type": "boolean", "description": "Boolean of whether the sync resulted in data being pushed." } } }, "Configuration": { "title": "Configuration", "type": "object", "x-internal": true, "properties": { "companyId": { "$ref": "#/components/parameters/companyId/schema" }, "accountingSoftwareCompanyName": { "type": "string", "description": "The company name defined in the accounting software." }, "enabled": { "type": "boolean", "description": "Enabled or disable bank feeds." }, "configured": { "type": "boolean", "description": "True if the company has been configured." }, "schedule": { "$ref": "#/components/schemas/Configuration/definitions/configurationSchedule" }, "configuration": { "$ref": "#/components/schemas/Configuration/definitions/syncConfiguration" } }, "definitions": { "configurationSchedule": { "title": "Configuration schedule", "type": "object", "properties": { "selectedFrequency": { "type": "string", "description": "The sync frequency." }, "frequencyOptions": { "type": "array", "items": { "type": "string" }, "description": "The available sync frequencies." }, "startDate": { "type": "string", "description": "The datetime in UTC you want to start syncing from." }, "syncHourUtc": { "type": "integer", "description": "The hour in which the sync is initiated." }, "timeZoneIanaId": { "type": "string", "description": "The [IANA](https://www.iana.org/time-zones) time zone ID." } } }, "syncConfiguration": { "title": "Sync configuration", "type": "object", "properties": { "syncAsBankFeeds": { "$ref": "#/components/schemas/Configuration/definitions/syncAsBankFeeds" }, "syncAsExpenses": { "$ref": "#/components/schemas/Configuration/definitions/syncAsExpenses" } } }, "syncAsBankFeeds": { "title": "Sync as bank feed", "type": "object", "properties": { "enableSync": { "type": "boolean", "description": "True if bank feeds sync is enabled." }, "selectedBankAccountId": { "type": "string", "description": "The bank account ID being synced." }, "bankAccountOptions": { "type": "array", "items": { "$ref": "#/components/schemas/Configuration/definitions/bankAccountOption" } } } }, "syncAsExpenses": { "title": "Sync as expenses", "type": "object", "properties": { "enableSync": { "type": "boolean", "description": "True if expense sync is enabled." }, "supplier": { "$ref": "#/components/schemas/Configuration/definitions/configurationSupplier" }, "customer": { "$ref": "#/components/schemas/Configuration/definitions/configurationCustomer" }, "selectedBankAccountId": { "type": "string", "description": "The bank account ID being synced." }, "bankAccountOptions": { "type": "array", "items": { "$ref": "#/components/schemas/Configuration/definitions/bankAccountOption" } } } }, "bankAccountOption": { "title": "Bank account option", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the bank account." }, "name": { "type": "string", "description": "Name of bank account." }, "accountType": { "type": "string", "description": "The type of account." } } }, "configurationSupplier": { "title": "Supplier configuration", "type": "object", "properties": { "selectedSupplierId": { "type": "string", "description": "Unique identifier for the supplier." }, "supplierOptions": { "type": "array", "items": { "$ref": "#/components/schemas/Configuration/definitions/configurationContactRef" } } } }, "configurationCustomer": { "title": "Customer configuration", "type": "object", "properties": { "selectedCustomerId": { "type": "string", "description": "Unique identifier for the customer." }, "customerOptions": { "type": "array", "items": { "$ref": "#/components/schemas/Configuration/definitions/configurationContactRef" } } } }, "configurationContactRef": { "title": "Supplier/customer reference", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the supplier/customer." }, "name": { "type": "string", "description": "The supplier/customer's name." } } } } }, "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": { "type": "string" } } }, "additionalProperties": false, "required": [ "id", "integrationId", "integrationKey", "sourceId", "platformName", "linkUrl", "status", "created", "sourceType" ], "definitions": { "dataConnectionStatus": { "title": "Data connection status", "description": "The current authorization status of the data connection.", "type": "string", "enum": [ "PendingAuth", "Linked", "Unlinked", "Deauthorized" ] }, "dataConnectionError": { "title": "Data connection error", "type": "object", "properties": { "statusCode": { "type": "string", "description": "The HTTP status code returned by the source platform when the error occurred." }, "statusText": { "type": "string", "description": "A non-numeric status code/text returned by the source platform when the error occurred." }, "errorMessage": { "type": "string", "description": "A message about a error returned by Codat." }, "erroredOnUtc": { "$ref": "#/components/schemas/DateTime" }, "status": { "title": "Error status", "description": "The current status of a transient error. Null statuses indicate that the error is not transient.", "type": "string", "nullable": true, "enum": [ "Active", "Resolved" ] }, "resolvedOnUtc": { "description": "The datetime in Utc that the error was resolved.", "nullable": true, "$ref": "#/components/schemas/DateTime" } } }, "dataConnectionSourceType": { "title": "Source Type", "description": "The type of platform of the connection.", "type": "string", "enum": [ "Accounting", "Banking", "BankFeed", "Commerce", "Expense", "Other", "Unknown" ], "example": "Accounting" } }, "example": { "id": "ee2eb431-c0fa-4dc9-93fa-d29781c12bcd", "integrationId": "bf083d72-62c7-493e-aec9-81b4dbba7e2c", "integrationKey": "dfxm", "sourceId": "bdd831ce-eebd-4896-89a7-20e5ee8989ee", "platformName": "Basiq", "linkUrl": "https://link-api.codat.io/companies/86bd88cb-44ab-4dfb-b32f-87b19b14287f/connections/ee2eb431-c0fa-4dc9-93fa-d29781c12bcd/start", "status": "Linked", "lastSync": "2022-10-27T10:22:43.6464237Z", "created": "2022-10-27T09:53:29Z", "sourceType": "Banking" } }, "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:00.000Z", "2022-10-23T00:00:00.000Z" ], "description": "In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example:\n\n```\n2020-10-08T22:40:50Z\n2021-01-01T00:00:00\n```\n\n\n\nWhen syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:\n\n- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`\n- Unqualified local time: `2021-11-15T01:00:00`\n- UTC time offsets: `2021-11-15T01:00:00-05:00`\n\n> Time zones\n> \n> Not all dates from Codat will contain information about time zones. \n> Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced." }, "ErrorMessage": { "title": "Error message", "type": "object", "x-internal": true, "properties": { "statusCode": { "type": "integer", "description": "The HTTP status code returned by the error." }, "service": { "type": "string", "description": "Codat's service the returned the error." }, "error": { "type": "string", "description": "A brief description of the error." }, "correlationId": { "type": "string", "description": "Unique identifier used to propagate to all downstream services and determine the source of the error." }, "validation": { "$ref": "#/components/schemas/ErrorMessage/definitions/errorValidation" }, "canBeRetried": { "type": "string", "description": "`True` if the error occurred transiently and can be retried." }, "detailedErrorCode": { "type": "integer", "description": "Machine readable error code used to automate processes based on the code returned." } }, "definitions": { "errorValidation": { "title": "Validation error", "type": "object", "nullable": true, "description": "A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.", "properties": { "errors": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ErrorMessage/definitions/errorValidationItem" } }, "warnings": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ErrorMessage/definitions/errorValidationItem" } } } }, "errorValidationItem": { "title": "Validation error item", "type": "object", "properties": { "itemId": { "type": "string", "nullable": true, "description": "Unique identifier for a validation item." }, "message": { "type": "string", "nullable": true, "description": "A message outlining validation item's issue." }, "validatorName": { "type": "string", "nullable": true, "description": "Name of validator." } } } } }, "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": { "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" } ] }, "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." }, "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": { "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-06T00:00:00.000Z", "availableBalance": 10 }, "modifiedDate": "2024-08-02T00:00:00.000Z", "status": "pending", "feedStartDate": "2024-05-01T00:00:00.000Z" }, { "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-23T00:00:00.000Z", "availableBalance": 400 }, "modifiedDate": "2024-08-02T00:00:00.000Z", "status": "pending", "feedStartDate": "2024-05-01T00:00:00.000Z" } ] }, "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": { "$ref": "#/components/schemas/SourceAccount" } } } } } }, "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/bank-feeds-api#/schemas/apiKeys) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/codat-api#/api-keys/api-keys-list), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.", "type": "apiKey", "in": "header", "x-speakeasy-example": "Basic BASE_64_ENCODED(API_KEY)" } } } }