{ "openapi": "3.1.0", "servers": [ { "description": "Production", "url": "https://api.codat.io" } ], "info": { "title": "Banking API", "summary": "Codat's standardized API for accessing banking data.", "description": "> ### New to Codat?\n>\n> Our Banking API reference is relevant only to our existing clients.\n> Please reach out to your Codat contact so that we can find the right product for you.\n\nCodat's Banking API allows you to access standardised data from over bank accounts via third party providers.\n\nStandardize how you connect to your customers’ bank accounts. Retrieve bank account and bank transaction data in the same way via our partnerships with Plaid and TrueLayer.\n\n\n## Endpoints\n\n| Endpoints | Description |\n| :- |:- |\n| Accounts | Where payments are made or received, and bank transactions are recorded. |\n| Account balances | Balances for a bank account including end-of-day batch balance or running balances per transaction. |\n| Transactions | An immutable source of up-to-date information on income and expenditure. |\n| Transaction categories | Hierarchical categories associated with a transaction for greater contextual meaning to transaction activity. |\n\n\n[Read more...](https://docs.codat.io/banking-api/overview)\n\n[See our OpenAPI spec](https://github.com/codatio/oas) ", "version": "3.0.0", "contact": { "name": "Codat", "email": "support@codat.io" }, "termsOfService": "https://www.codat.io/legals/" }, "security": [ { "auth_header": [] } ], "x-speakeasy-retries": { "strategy": "backoff", "backoff": { "initialInterval": 500, "maxInterval": 60000, "maxElapsedTime": 3600000, "exponent": 1.5 }, "statusCodes": [ 408, 429, "5XX" ], "retryConnectionErrors": true }, "x-speakeasy-name-override": [ { "operationId": "^list*", "methodNameOverride": "list" }, { "operationId": "^get*", "methodNameOverride": "get" } ], "x-codat-docs-path": "codat-api", "x-codat-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page", "in": "parameters", "type": "page" } ], "outputs": { "results": "$.results" } }, "tags": [ { "name": "Accounts", "description": "Where payments are made or received, and bank transactions are recorded." }, { "name": "Account balances", "description": "Balances for a bank account including end-of-day batch balance or running balances per transaction." }, { "name": "Transactions", "description": "An immutable source of up-to-date information on income and expenditure." }, { "name": "Transaction categories", "description": "Hierarchical categories associated with a transaction for greater contextual meaning to transaction activity." } ], "paths": { "/companies/{companyId}/connections/{connectionId}/data/banking-accountBalances": { "get": { "tags": [ "Account balances" ], "summary": "List account balances", "operationId": "list-account-balances", "description": "The *List account balances* endpoint returns a list of [account balances](https://docs.codat.io/banking-api#/schemas/AccountBalance) for a given company's connection.\n\n[Account balances](https://docs.codat.io/banking-api#/schemas/AccountBalance) are balances for a bank account, including end-of-day batch balance or running balances per transaction.\n\nBefore using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data).\n ", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$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/AccountBalances" }, "examples": { "Basiq": { "value": { "results": [ { "accountId": "4811e776-6187-48d9-afee-635fb0d89d93", "balance": { "current": 11389.85 }, "date": "2017-12-31T00:00:00Z", "modifiedDate": "2022-10-28T07:15:07Z" }, { "accountId": "4811e776-6187-48d9-afee-635fb0d89d93", "balance": { "current": 8002.09 }, "date": "2018-01-01T00:00:00Z", "modifiedDate": "2022-10-28T07:15:07Z" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 3103, "_links": { "current": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-accountBalances?page=1&pageSize=2" }, "self": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-accountBalances" }, "next": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-accountBalances?page=2&pageSize=2" } } } }, "Plaid": { "value": { "results": [ { "accountId": "3opGv6XXNeHPEgNVbQpyCr8MAKQ3noC8Qz1zB", "balance": { "current": 205.78 }, "date": "2022-10-13T00:00:00", "modifiedDate": "2022-10-27T10:50:16Z" }, { "accountId": "3opGv6XXNeHPEgNVbQpyCr8MAKQ3noC8Qz1zB", "balance": { "current": 205.78 }, "date": "2022-10-14T00:00:00", "modifiedDate": "2022-10-27T10:50:16Z" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 14, "_links": { "current": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-accountBalances?page=1&pageSize=2" }, "self": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-accountBalances" }, "next": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-accountBalances?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" } } } }, "/companies/{companyId}/connections/{connectionId}/data/banking-accounts": { "get": { "tags": [ "Accounts" ], "summary": "List accounts", "operationId": "list-accounts", "description": "The *List accounts* endpoint returns a list of [accounts](https://docs.codat.io/banking-api#/schemas/Account) for a given company's connection.\n\n[Accounts](https://docs.codat.io/banking-api#/schemas/Account) 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/codat-api#/operations/refresh-company-data).\n ", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "$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/Accounts" }, "examples": { "Basiq": { "value": { "results": [ { "id": "4811e776-6187-48d9-afee-635fb0d89d93", "name": "Hooli Saver", "holder": "david smith", "type": "Debit", "balance": { "available": 2932.85, "current": 2932.85 }, "identifiers": { "type": "Account", "number": "14293919644182", "bankCode": "416-982" }, "currency": "AUD", "institution": { "id": "AU00000", "name": "Hooli Bank" }, "modifiedDate": "2022-10-28T07:14:48Z", "sourceModifiedDate": "2022-10-27T13:00:00Z", "accountName": "Hooli Saver", "accountHolder": "david smith", "accountType": "Debit", "accountNumbers": { "type": "Account", "number": "14293919644182", "bankCode": "416-982" } }, { "id": "736d90a5-f836-4ae0-a161-1e8056f39701", "name": "Standard Variable Rate Home Loan", "holder": "david smith", "type": "Credit", "balance": { "available": 6940.31, "current": 6940.31 }, "identifiers": { "type": "Loan", "number": "14293919644183", "bankCode": "416-982" }, "currency": "AUD", "institution": { "id": "AU00000", "name": "Hooli Bank" }, "modifiedDate": "2022-10-28T07:14:48Z", "sourceModifiedDate": "2022-10-27T13:00:00Z", "accountName": "Standard Variable Rate Home Loan", "accountHolder": "david smith", "accountType": "Credit", "accountNumbers": { "type": "Loan", "number": "14293919644183", "bankCode": "416-982" } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 4, "_links": { "current": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-accounts?page=1&pageSize=2" }, "self": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-accounts" }, "next": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-accounts?page=2&pageSize=2" } } } }, "Plaid": { "value": { "results": [ { "id": "3opGv6XXNeHPEgNVbQpyCr8MAKQ3noC8Qz1zB", "name": "Plaid Silver Standard 0.1% Interest Saving", "informalName": "Plaid Saving", "type": "Debit", "balance": { "available": 200, "current": 210 }, "identifiers": { "type": "Depository", "number": "1111222233331111", "bankCode": "00021", "maskedAccountNumber": "1111" }, "currency": "CAD", "institution": { "id": "ins_100533", "name": "American Express (CA)" }, "modifiedDate": "2022-10-27T10:50:16Z", "accountName": "Plaid Silver Standard 0.1% Interest Saving", "accountType": "Debit", "accountNumbers": { "type": "Depository", "number": "1111222233331111", "bankCode": "00021", "maskedAccountNumber": "1111" } } ], "pageNumber": 1, "pageSize": 2, "totalResults": 1, "_links": { "current": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-accounts?page=1&pageSize=2" }, "self": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-accounts" } } } } } } } }, "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" } } } }, "/companies/{companyId}/connections/{connectionId}/data/banking-accounts/{accountId}": { "get": { "tags": [ "Accounts" ], "summary": "Get account", "operationId": "get-account", "description": "The *Get account* endpoint returns a single account for a given accountId.\n\n[Accounts](https://docs.codat.io/banking-api#/schemas/Account) are financial accounts maintained by a bank or other financial institution.\n\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/banking?view=tab-by-data-type&dataType=banking-accounts) for integrations that support getting a specific account.\n\nBefore using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data).\n", "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "13d946f0-c5d5-42bc-b092-97ece17923ab", "9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2", 7110701885, "EILBDVJVNUAGVKRQ" ] }, "description": "Unique identifier for an account." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "examples": { "Basiq": { "value": { "id": "4811e776-6187-48d9-afee-635fb0d89d93", "name": "Hooli Saver", "holder": "david smith", "type": "Debit", "balance": { "available": 2932.85, "current": 2932.85 }, "identifiers": { "type": "Account", "number": "14293919644182", "bankCode": "416-982" }, "currency": "AUD", "institution": { "id": "AU00000", "name": "Hooli Bank" }, "modifiedDate": "2022-10-28T07:14:48Z", "sourceModifiedDate": "2022-10-27T13:00:00Z", "accountName": "Hooli Saver", "accountHolder": "david smith", "accountType": "Debit", "accountNumbers": { "type": "Account", "number": "14293919644182", "bankCode": "416-982" } } }, "Plaid": { "value": { "id": "3opGv6XXNeHPEgNVbQpyCr8MAKQ3noC8Qz1zB", "name": "Plaid Silver Standard 0.1% Interest Saving", "informalName": "Plaid Saving", "type": "Debit", "balance": { "available": 200, "current": 210 }, "identifiers": { "type": "Depository", "number": "1111222233331111", "bankCode": "00021", "maskedAccountNumber": "1111" }, "currency": "CAD", "institution": { "id": "ins_100533", "name": "American Express (CA)" }, "modifiedDate": "2022-10-27T10:50:16Z", "accountName": "Plaid Silver Standard 0.1% Interest Saving", "accountType": "Debit", "accountNumbers": { "type": "Depository", "number": "1111222233331111", "bankCode": "00021", "maskedAccountNumber": "1111" } } } } } } }, "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" } } } }, "/companies/{companyId}/connections/{connectionId}/data/banking-transactionCategories": { "get": { "tags": [ "Transaction categories" ], "operationId": "list-transaction-categories", "summary": "List transaction categories", "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/TransactionCategories" }, "examples": { "Basiq": { "value": { "results": [ { "id": "bank-fee", "name": "Bank Fee", "hasChildren": false, "status": "Active", "modifiedDate": "2022-10-28T07:14:46" }, { "id": "cash-withdrawal", "name": "Cash Withdrawal", "hasChildren": false, "status": "Active", "modifiedDate": "2022-10-28T07:14:46" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 9, "_links": { "current": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-transactionCategories?page=1&pageSize=2" }, "self": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-transactionCategories" }, "next": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-transactionCategories?page=2&pageSize=2" } } } }, "Plaid": { "value": { "results": [ { "id": "BANK_FEES", "name": "BANK_FEES", "hasChildren": true, "status": "Active", "modifiedDate": "2022-10-27T10:50:17" }, { "id": "BANK_FEES.BANK_FEES_ATM_FEES", "name": "BANK_FEES_ATM_FEES", "parentId": "BANK_FEES", "hasChildren": false, "status": "Active", "modifiedDate": "2022-10-27T10:50:17" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 120, "_links": { "current": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-transactionCategories?page=1&pageSize=2" }, "self": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-transactionCategories" }, "next": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-transactionCategories?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 transaction categories* endpoint returns a list of [transaction categories](https://docs.codat.io/banking-api#/schemas/TransactionCategory) for a given company's connection.\n\n[Transaction categories](https://docs.codat.io/banking-api#/schemas/TransactionCategory) are associated with a transaction to provide greater contextual meaning to transaction activity.\n\nBefore using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data).\n " }, "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ] }, "/companies/{companyId}/connections/{connectionId}/data/banking-transactionCategories/{transactionCategoryId}": { "get": { "tags": [ "Transaction categories" ], "operationId": "get-transaction-category", "summary": "Get transaction category", "description": "The *Get transaction category* endpoint returns a single transaction category for a given transactionCategoryId.\n\n[Transaction categories](https://docs.codat.io/banking-api#/schemas/TransactionCategory) are associated with a transaction to provide greater contextual meaning to transaction activity.\n\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/banking?view=tab-by-data-type&dataType=banking-transactionCategories) for integrations that support getting a specific transaction category.\n\nBefore using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data).\n", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCategory" }, "examples": { "Basiq": { "value": { "id": "bank-fee", "name": "Bank Fee", "hasChildren": false, "status": "Active", "modifiedDate": "2022-10-28T07:14:46" } }, "Plaid": { "value": { "id": "BANK_FEES", "name": "BANK_FEES", "hasChildren": true, "status": "Active", "modifiedDate": "2022-10-27T10:50:17" } } } } } }, "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" } } }, "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "schema": { "type": "string" }, "name": "transactionCategoryId", "in": "path", "required": true, "description": "The unique identifier for a banking transaction category" } ] }, "/companies/{companyId}/connections/{connectionId}/data/banking-transactions": { "get": { "tags": [ "Transactions" ], "operationId": "list-transactions", "summary": "List transactions", "description": "The *List transactions* endpoint returns a list of [transactions](https://docs.codat.io/banking-api#/schemas/Transaction) for a given company's connection.\n\n[Transactions](https://docs.codat.io/banking-api#/schemas/Transaction) provide an immutable source of up-to-date information on income and expenditure.\n\nBefore using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data).\n ", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/orderBy" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "x-speakeasy-usage-example": true, "schema": { "$ref": "#/components/schemas/Transactions" }, "examples": { "Basiq": { "value": { "results": [ { "id": "00017a94-c681-448d-ba8d-585a81b4128f", "accountId": "feb76128-7650-4b02-a323-e1606146be0c", "description": "RENTALCARTOLLPH131865 PARRAMATTA AU Card xx0399 Value Date: 25/07/2019", "amount": -14.26, "currency": "AUD", "postedDate": "2019-07-31T00:00:00Z", "code": "Unknown", "merchantName": "", "transactionCategoryRef": { "id": "payment", "name": "Payment" }, "modifiedDate": "2022-10-28T07:15:10Z" }, { "id": "0023c431-35c8-41f5-b75e-9239413cde7e", "accountId": "4811e776-6187-48d9-afee-635fb0d89d93", "description": "Transfer from xx9263 CommBank app Shop", "amount": 191, "currency": "AUD", "postedDate": "2018-07-31T00:00:00Z", "code": "Unknown", "merchantName": "", "transactionCategoryRef": { "id": "transfer", "name": "Transfer" }, "modifiedDate": "2022-10-28T07:15:10Z" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 3319, "_links": { "current": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-transactions?page=1&pageSize=2" }, "self": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-transactions" }, "next": { "href": "/companies/17129e41-5389-4f10-ac06-e0a37e47d177/connections/b4703906-e631-46f1-9acc-7e237acdc64d/data/banking-transactions?page=2&pageSize=2" } } } }, "Plaid": { "value": { "results": [ { "id": "1514wvMMajumgG7xWA1Bt8o15xP5k3fmeo9Bg_EC6E0DC820E1F9D1A2300BF4A5B80513", "accountId": "3opGv6XXNeHPEgNVbQpyCr8MAKQ3noC8Qz1zB", "description": "CREDIT CARD 3333 PAYMENT *//", "amount": -25, "currency": "CAD", "postedDate": "2021-05-10T00:00:00", "authorizedDate": "2021-05-09T00:00:00", "code": "Unknown", "transactionCategoryRef": { "id": "TRANSFER_OUT.TRANSFER_OUT_ACCOUNT_TRANSFER", "name": "TRANSFER_OUT_ACCOUNT_TRANSFER" }, "modifiedDate": "2022-10-27T10:50:25Z" }, { "id": "1514wvMMajumgG7xWA1Bt8oDLxlpm3i3zraD7_6DB63D1DACF6F5824C80F8BE2E066DB5", "accountId": "3opGv6XXNeHPEgNVbQpyCr8MAKQ3noC8Qz1zB", "description": "CREDIT CARD 3333 PAYMENT *//", "amount": -25, "currency": "CAD", "postedDate": "2022-10-02T00:00:00", "authorizedDate": "2022-10-01T00:00:00", "code": "Unknown", "transactionCategoryRef": { "id": "TRANSFER_OUT.TRANSFER_OUT_ACCOUNT_TRANSFER", "name": "TRANSFER_OUT_ACCOUNT_TRANSFER" }, "modifiedDate": "2022-10-27T10:50:25Z" } ], "pageNumber": 1, "pageSize": 2, "totalResults": 49, "_links": { "current": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-transactions?page=1&pageSize=2" }, "self": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-transactions" }, "next": { "href": "/companies/efc2d985-cdb3-4724-8be3-c7310f7ead6c/connections/6c44dc44-e1b1-4578-800f-0bdefb658db7/data/banking-transactions?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" } } }, "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" } ] }, "/companies/{companyId}/data/banking-transactions": { "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "get": { "tags": [ "Transactions" ], "operationId": "list-bank-transactions", "x-speakeasy-name-override": "list-bank-transactions", "deprecated": true, "x-speakeasy-deprecation-replacement": "list-transactions", "summary": "List banking transactions", "description": "The *List transactions* endpoint returns a list of [transactions](https://docs.codat.io/banking-api#/schemas/Transaction) for a given company's connection.\n\n[Transactions](https://docs.codat.io/banking-api#/schemas/Transaction) provide an immutable source of up-to-date information on income and expenditure.\n\nBefore using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data).\n ", "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/Transactions" }, "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" }, "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" } } } }, "/companies/{companyId}/connections/{connectionId}/data/banking-transactions/{transactionId}": { "get": { "tags": [ "Transactions" ], "summary": "Get bank transaction", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "Basiq": { "value": { "id": "00017a94-c681-448d-ba8d-585a81b4128f", "accountId": "feb76128-7650-4b02-a323-e1606146be0c", "description": "RENTALCARTOLLPH131865 PARRAMATTA AU Card xx0399 Value Date: 25/07/2019", "amount": -14.26, "currency": "AUD", "postedDate": "2019-07-31T00:00:00Z", "code": "Unknown", "merchantName": "", "transactionCategoryRef": { "id": "payment", "name": "Payment" }, "modifiedDate": "2022-10-28T07:15:10Z" } }, "Plaid": { "value": { "id": "1514wvMMajumgG7xWA1Bt8o15xP5k3fmeo9Bg_EC6E0DC820E1F9D1A2300BF4A5B80513", "accountId": "3opGv6XXNeHPEgNVbQpyCr8MAKQ3noC8Qz1zB", "description": "CREDIT CARD 3333 PAYMENT *//", "amount": -25, "currency": "CAD", "postedDate": "2021-05-10T00:00:00", "authorizedDate": "2021-05-09T00:00:00", "code": "Unknown", "transactionCategoryRef": { "id": "TRANSFER_OUT.TRANSFER_OUT_ACCOUNT_TRANSFER", "name": "TRANSFER_OUT_ACCOUNT_TRANSFER" }, "modifiedDate": "2022-10-27T10:50:25Z" } } } } } }, "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 *Get transaction* endpoint returns a single transaction for a given transactionId.\n\n[Transactions](https://docs.codat.io/banking-api#/schemas/Transaction) provide an immutable source of up-to-date information on income and expenditure.\n\nCheck out our [coverage explorer](https://knowledge.codat.io/supported-features/banking?view=tab-by-data-type&dataType=banking-transactions) for integrations that support getting a specific transaction.\n\nBefore using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data).\n", "operationId": "get-transaction" }, "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/connectionId" }, { "schema": { "type": "string" }, "name": "transactionId", "in": "path", "required": true, "description": "The unique identifier for a transaction" } ] } }, "components": { "schemas": { "Account": { "title": "Banking: Bank account", "description": "This data type provides a list of all the SMB's bank accounts, with rich data like balances, account numbers, and institutions holding the accounts.\n\nExplore our [data coverage](https://knowledge.codat.io/supported-features/banking?view=tab-by-data-type&dataType=banking-accounts).\n\nResponses are paged, so you should provide `page` and `pageSize` query parameters in your request.", "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "minLength": 1, "type": "string", "description": "The ID of the account from the provider." }, "name": { "minLength": 1, "type": "string", "description": "The name of the account according to the provider." }, "informalName": { "type": "string", "nullable": true, "description": "The friendly name of the account, chosen by the holder. This may not have been set by the account holder and therefore is not always available." }, "holder": { "type": "string", "nullable": true, "description": "The name of the person or company who holds the account." }, "type": { "$ref": "#/components/schemas/AccountType" }, "balance": { "$ref": "#/components/schemas/AccountBalance/definitions/accountBalanceAmounts", "description": "An object containing bank balance data." }, "identifiers": { "$ref": "#/components/schemas/Account/definitions/accountIdentifiers" }, "currency": { "minLength": 1, "type": "string", "description": "The currency code for the account." }, "institution": { "$ref": "#/components/schemas/Account/definitions/accountInstitution" } } }, { "$ref": "#/components/schemas/ModifiedDates" } ], "required": [ "id", "name", "type", "balance", "identifiers", "currency", "institution" ], "definitions": { "accountIdentifiers": { "title": "Account Identifiers", "description": "An object containing bank account identification information.", "type": "object", "x-internal": true, "additionalProperties": false, "properties": { "type": { "$ref": "#/components/schemas/Account/definitions/accountIdentifierType" }, "subtype": { "type": "string", "nullable": true, "description": "Detailed account category" }, "number": { "type": "string", "nullable": true, "description": "The account number for the account. When combined with the`bankCode`, this is usually enough to uniquely identify an account within a jurisdiction." }, "bankCode": { "type": "string", "nullable": true, "description": "The local (usually national) routing number for the account.\n\nThis is known by different names in different countries:\n* BSB code (Australia)\n* routing number (Canada, USA)\n* sort code (UK)" }, "iban": { "type": "string", "nullable": true, "description": "The international bank account number (IBAN) for the account, if known." }, "bic": { "type": "string", "nullable": true, "description": "The ISO 9362 code (commonly called SWIFT code, SWIFT-BIC or BIC) for the account." }, "maskedAccountNumber": { "type": "string", "nullable": true, "description": "A portion of the actual account `number` to help account identification where number is tokenised (Plaid only)" } }, "required": [ "type" ] }, "accountIdentifierType": { "type": "string", "x-internal": true, "description": "Type of account", "enum": [ "Account", "Card", "Credit", "Depository", "Investment", "Loan", "Other" ] }, "accountInstitution": { "title": "Account Institution", "description": "The bank or other financial institution providing the account.", "x-internal": true, "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The institution's ID, according to the provider." }, "name": { "type": "string", "description": "The institution's name, according to the underlying provider." } } } }, "examples": [ { "results": [ { "id": "1703194f-7805-4da8-bac0-2ba5da4a4216", "name": "Business Current Account", "informalName": "Codat", "holder": "Codat Ltd", "type": "Debit", "balance": { "available": -459987.97, "current": -459964.9, "limit": 5000 }, "identifiers": { "type": "Depository", "subtype": "checking", "number": "46762629", "bankCode": "009911", "iban": "GB29 LOYD 4773 2346 7626 29", "bic": "LOYDGB21006", "maskedAccountNumber": "LOYDGB21006" }, "currency": "GBP", "institution": { "id": "lloyds-bank", "name": "Lloyds Bank" }, "modifiedDate": "2022-05-23T16:32:50Z", "sourceModifiedDate": "2021-08-14T05:04:12" } ] } ] }, "AccountBalance": { "title": "Banking: Account balance", "description": "The Banking Account Balances data type provides a list of balances for a bank account including end-of-day batch balance or running balances per transaction.\n\nResponses are paged, so you should provide `page` and `pageSize` query parameters in your request.\n\n> **How often should I pull Account Balances?**\n>\n> Because these balances are closing balances, we recommend you pull Account Balance no more frequently than daily. If you require a live intraday balance, this can be found for each account on the [Account](https://docs.codat.io/banking-api#/schemas/Account) data type.\n> \n> Whilst you can choose to sync hourly, this may incur usage charges from Plaid or TrueLayer.", "type": "object", "allOf": [ { "type": "object", "properties": { "accountId": { "minLength": 1, "type": "string", "description": "The unique identifier of the account." }, "balance": { "$ref": "#/components/schemas/AccountBalance/definitions/accountBalanceAmounts" }, "date": { "$ref": "#/components/schemas/DateTime", "description": "Date of the balance." } } }, { "$ref": "#/components/schemas/ModifiedDates" } ], "required": [ "accountId", "balance", "date" ], "definitions": { "accountBalanceAmounts": { "title": "Account Balance Amounts", "x-internal": true, "type": "object", "properties": { "available": { "type": "number", "format": "decimal", "nullable": true, "description": "The balance available in the account, including any pending transactions. This doesn't include additional funds available from any overdrafts." }, "current": { "type": "number", "format": "decimal", "description": "The balance of the account only including cleared transactions." }, "limit": { "type": "number", "format": "decimal", "nullable": true, "description": "The minimum allowed balance for the account. For example, a $100.00 overdraft would show as a limit of `-100.00`." } }, "additionalProperties": false, "description": "Depending on the data provided by the underlying bank, not all balances are always available." } }, "examples": [ { "accountBalances": [ { "accountId": "cce404db-27f7-4286-95db-622b53596cf4", "balance": { "available": 714374.48, "current": 714374.57, "limit": 5000 }, "date": "2021-03-18T00:00:00" }, { "accountId": "cce404db-27f7-4286-95db-622b53596cf4", "balance": { "available": 714374.48, "current": 714374.57, "limit": 5000 }, "date": "2021-03-19T00:00:00" }, { "accountId": "cce404db-27f7-4286-95db-622b53596cf4", "balance": { "available": 714195.66, "current": 714204.39, "limit": 5000 }, "date": "2021-03-22T00:00:00" }, { "accountId": "2f593774-1075-4805-a552-84eecc7eb264", "balance": { "available": -644945.42, "current": -644925.84, "limit": 0 }, "date": "2022-03-09T00:00:00" } ] } ] }, "AccountBalances": { "title": "Banking: Account balances", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBalance" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "Accounts": { "title": "Banking: Bank accounts", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "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." }, "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." } } } } }, "ModifiedDate": { "title": "ModifiedDate", "x-internal": true, "type": "object", "properties": { "modifiedDate": { "allOf": [ { "$ref": "#/components/schemas/DateTime" }, { "description": "The date when the record was last fetched from the data source and updated in Codat’s data cache. \n\nUse it to identify and retrieve records that have changed since your last fetch. For example, filtering `modifiedDate` to today will provide new records updated in Codat today.\n\nThis date is populated for all data types except for attachments, balance sheets, company information, and profit & loss reports ([read more](https://docs.codat.io/using-the-api/modified-dates#modified-date)).\n\nIn Codat's data model, dates and times are represented using the ISO 8601 standard." } ] } } }, "ModifiedDates": { "title": "Modified dates", "x-internal": true, "allOf": [ { "$ref": "#/components/schemas/ModifiedDate" }, { "$ref": "#/components/schemas/SourceModifiedDate" } ] }, "PagingInfo": { "type": "object", "title": "Pagination information", "x-internal": true, "properties": { "pageNumber": { "type": "integer", "description": "Current page number." }, "pageSize": { "type": "integer", "description": "Number of items to return in results array.", "maximum": 2000 }, "totalResults": { "type": "integer", "description": "Total number of items." }, "_links": { "$ref": "#/components/schemas/PagingInfo/definitions/links" } }, "definitions": { "links": { "title": "Hal Links", "type": "object", "required": [ "self", "current" ], "properties": { "self": { "$ref": "#/components/schemas/PagingInfo/definitions/halRef" }, "current": { "$ref": "#/components/schemas/PagingInfo/definitions/halRef" }, "next": { "$ref": "#/components/schemas/PagingInfo/definitions/halRef" }, "previous": { "$ref": "#/components/schemas/PagingInfo/definitions/halRef" } }, "examples": [ { "self": { "href": "/companies" }, "current": { "href": "/companies?page=1&pageSize=10" } } ] }, "halRef": { "title": "Hypertext reference", "type": "object", "properties": { "href": { "type": "string", "format": "uri-reference", "description": "Uri hypertext reference." } } } }, "required": [ "pageNumber", "pageSize", "totalResults", "_links" ], "examples": [ { "pageNumber": 1, "pageSize": 10, "totalResults": 1, "_links": { "self": { "href": "/companies/{id}/data/{dataType}" }, "current": { "href": "/companies/{id}/data/{dataType}?page=1&pageSize=10" } } } ] }, "SourceModifiedDate": { "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." } ] } } }, "Transaction": { "title": "Banking: Transaction", "description": "The Banking Transactions data type provides an immutable source of up-to-date information on income and expenditure.\n\nResponses are paged, so you should provide `page` and `pageSize` query parameters in your request.\n\nView the coverage for banking transactions in the [Data Coverage Explorer](https://knowledge.codat.io/supported-features/banking?view=tab-by-data-type&dataType=banking-transactions).", "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "minLength": 1, "type": "string", "description": "The unique identifier of the bank transaction." }, "accountId": { "minLength": 1, "type": "string", "description": "The unique identifier of the bank account." }, "description": { "type": "string", "nullable": true, "description": "The description of the bank transaction." }, "amount": { "type": "number", "format": "decimal", "description": "The amount of the bank transaction." }, "currency": { "minLength": 1, "type": "string", "description": "The currency of the bank transaction." }, "postedDate": { "$ref": "#/components/schemas/DateTime", "description": "The date the bank transaction was cleared." }, "authorizedDate": { "$ref": "#/components/schemas/DateTime", "description": "The date the bank transaction was authorized." }, "code": { "$ref": "#/components/schemas/Transaction/definitions/transactionCode" }, "merchantName": { "type": "string", "nullable": true, "description": "The name of the merchant." }, "transactionCategoryRef": { "$ref": "#/components/schemas/TransactionCategory/definitions/transactionCategoryRef" } } }, { "$ref": "#/components/schemas/ModifiedDates" } ], "required": [ "id", "accountId", "currency" ], "definitions": { "transactionCode": { "type": "string", "x-internal": true, "description": "Code to identify the underlying transaction.", "enum": [ "Unknown", "Fee", "Payment", "Cash", "Transfer", "Interest", "Cashback", "Cheque", "DirectDebit", "Purchase", "StandingOrder", "Adjustment", "Credit", "Other", "NotSupported" ] } }, "examples": [ { "id": "0130b5bb-1419-40f6-8a27-7362d0381229", "accountId": "1703194f-7805-4da8-bac0-2ba5da4a4216", "description": "Payments for direct income ce149943-c157-43fc-aac7-42a716b655b6", "amount": 5062.39, "currency": "GBP", "postedDate": "2021-07-06T00:00:00", "authorizedDate": "2021-07-06T00:00:00", "merchantName": "New Look", "transactionCategoryRef": { "id": "health-and-fitness-sports" }, "modifiedDate": "2022-05-23T16:32:50Z", "sourceModifiedDate": "2021-06-28T10:48:12" } ] }, "TransactionCategories": { "title": "Banking: Transaction categories", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionCategory" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] }, "TransactionCategory": { "title": "Banking: Transaction category", "description": "The Banking Transaction Categories data type provides a list of hierarchical categories associated with a transaction for greater contextual meaning to transaction activity.\n\nResponses are paged, so you should provide `page` and `pageSize` query parameters in your request.", "type": "object", "allOf": [ { "type": "object", "description": "Status of the bank transaction category.", "properties": { "id": { "minLength": 1, "type": "string", "description": "The unique identifier of the bank transaction category." }, "name": { "minLength": 1, "type": "string", "description": "The name of the bank transaction category." }, "parentId": { "type": "string", "nullable": true, "description": "The unique identifier of the parent bank transaction category." }, "hasChildren": { "type": "boolean", "description": "A Boolean indicating whether there are other bank transaction categories beneath this one in the hierarchy." }, "status": { "$ref": "#/components/schemas/TransactionCategory/definitions/transactionCategoryStatus" } } }, { "$ref": "#/components/schemas/ModifiedDates" } ], "required": [ "id", "name" ], "definitions": { "transactionCategoryRef": { "type": "object", "x-internal": true, "description": "An object of bank transaction category reference data.", "properties": { "id": { "minLength": 1, "type": "string", "description": "The unique category reference id for the bank transaction." }, "name": { "type": "string", "nullable": true, "description": "The category name reference for the bank transaction." } }, "required": [ "id" ] }, "transactionCategoryStatus": { "type": "string", "description": "The status of the transaction category.", "x-internal": true, "enum": [ "Unknown", "Active", "Archived" ] } }, "examples": [ { "id": "auto-and-transport", "name": "Auto & Transport", "hasChildren": true, "status": "Active", "modifiedDate": "2022-05-23T16:32:50", "sourceModifiedDate": "2021-04-24T07:59:10" } ] }, "Transactions": { "title": "Banking: Transactions", "x-internal": true, "allOf": [ { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } }, { "$ref": "#/components/schemas/PagingInfo" } ] } }, "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." }, "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)." } }, "responses": { "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/accounting-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)" } } } }