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? > > Our Banking API reference is relevant only to our existing clients. > Please reach out to your Codat contact so that we can find the right product for you. Codat's Banking API allows you to access standardised data from over bank accounts via third party providers. Standardize 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. ## Endpoints | Endpoints | Description | | :- |:- | | Accounts | Where payments are made or received, and bank transactions are recorded. | | Account balances | Balances for a bank account including end-of-day batch balance or running balances per transaction. | | Transactions | An immutable source of up-to-date information on income and expenditure. | | Transaction categories | Hierarchical categories associated with a transaction for greater contextual meaning to transaction activity. | [Read more...](https://docs.codat.io/banking-api/overview) [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. [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. Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data). 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. [Accounts](https://docs.codat.io/banking-api#/schemas/Account) are financial accounts maintained by a bank or other financial institution. Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data). 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. [Accounts](https://docs.codat.io/banking-api#/schemas/Account) are financial accounts maintained by a bank or other financial institution. Check 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. Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data). 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. [Transaction categories](https://docs.codat.io/banking-api#/schemas/TransactionCategory) are associated with a transaction to provide greater contextual meaning to transaction activity. Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data). 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. [Transaction categories](https://docs.codat.io/banking-api#/schemas/TransactionCategory) are associated with a transaction to provide greater contextual meaning to transaction activity. Check 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. Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data). 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. [Transactions](https://docs.codat.io/banking-api#/schemas/Transaction) provide an immutable source of up-to-date information on income and expenditure. Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data). 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. [Transactions](https://docs.codat.io/banking-api#/schemas/Transaction) provide an immutable source of up-to-date information on income and expenditure. Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data). 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. [Transactions](https://docs.codat.io/banking-api#/schemas/Transaction) provide an immutable source of up-to-date information on income and expenditure. Check 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. Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/codat-api#/operations/refresh-company-data). 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. Explore our [data coverage](https://knowledge.codat.io/supported-features/banking?view=tab-by-data-type&dataType=banking-accounts). Responses 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. This is known by different names in different countries: * BSB code (Australia) * routing number (Canada, USA) * 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. Responses are paged, so you should provide `page` and `pageSize` query parameters in your request. > **How often should I pull Account Balances?** > > 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. > > 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. For Credit accounts, positive balances are liabilities, and positive transactions **reduce** liabilities. For 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: ``` 2020-10-08T22:40:50Z 2021-01-01T00:00:00 ``` When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information: - Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z` - Unqualified local time: `2021-11-15T01:00:00` - UTC time offsets: `2021-11-15T01:00:00-05:00` > Time zones > > Not all dates from Codat will contain information about time zones. > 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. Use 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. This 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)). In 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. It is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when: - Pulling attachments - The integration platform does not provide modification dates for a data type - A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred - A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records In 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. Responses are paged, so you should provide `page` and `pageSize` query parameters in your request. View 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. Responses 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: - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io. 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. This 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)