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: |- 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. [Read more...](https://docs.codat.io/banking-api/overview) [See our OpenAPI spec](https://github.com/codatio/oas) version: 2.1.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 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: Gets a list of balances for a bank account including end-of-day batch balance or running balances per transaction. 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' '/companies/{companyId}/connections/{connectionId}/data/banking-accounts': get: tags: - Accounts summary: List accounts operationId: list-accounts description: 'Gets a list of all bank accounts of the SMB, with rich data like balances, account numbers and institutions holdingthe accounts.' 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' '/companies/{companyId}/connections/{connectionId}/data/banking-accounts/{accountId}': get: tags: - Accounts summary: Get account operationId: get-account deprecated: true description: Gets a specified bank account for a given company x-internal: true parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' - name: accountId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for an account responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Account' '/companies/{companyId}/connections/{connectionId}/data/banking-transactionCategories': get: tags: - Transaction categories summary: List all 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' description: Gets a list of hierarchical categories associated with a transaction for greater contextual meaning to transactionactivity. operationId: list-transaction-categories parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' '/companies/{companyId}/connections/{connectionId}/data/banking-transactionCategories/{transactionCategoryId}': get: tags: - Transaction categories summary: Get transaction category responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/TransactionCategory' deprecated: true operationId: get-transaction-category description: Gets a specified bank transaction category for a given company x-internal: true 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 summary: List transactions 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' description: Gets a list of transactions incurred by a bank account. operationId: list-transactions parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' '/companies/{companyId}/data/banking-transactions': parameters: - $ref: '#/components/parameters/companyId' get: tags: - Transactions summary: List banking transactions 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' description: Gets a list of transactions incurred by a company across all bank accounts. operationId: list-bank-transactions '/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' description: Gets a specified bank transaction for a given company operationId: get-transaction deprecated: true x-internal: true parameters: - $ref: '#/components/parameters/companyId' - schema: type: string name: transactionId in: path required: true description: The unique identifier for a transaction - $ref: '#/components/parameters/connectionId' components: schemas: DateTime: title: Date time type: string example: '2022-10-23T00:00:00Z' 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. AccountBalance: title: 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 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 description: The balance of the account only including cleared transactions. limit: type: number 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: x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/AccountBalance' - $ref: '#/components/schemas/PagingInfo' Account: title: 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' Accounts: x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/Account' - $ref: '#/components/schemas/PagingInfo' Transaction: title: 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 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' Transactions: x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/Transaction' - $ref: '#/components/schemas/PagingInfo' TransactionCategory: title: 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 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' TransactionCategories: x-internal: true allOf: - type: object properties: results: type: array items: $ref: '#/components/schemas/TransactionCategory' - $ref: '#/components/schemas/PagingInfo' ModifiedDates: x-internal: true allOf: - $ref: '#/components/schemas/ModifiedDate' - $ref: '#/components/schemas/SourceModifiedDate' ModifiedDate: title: ModifiedDate x-internal: true type: object properties: modifiedDate: $ref: '#/components/schemas/DateTime' description: The date on which this record was last modified in Codat. SourceModifiedDate: title: Source Modified Date x-internal: true type: object properties: sourceModifiedDate: $ref: '#/components/schemas/DateTime' description: The date on which this record was last modified in the originating system Links: type: object x-internal: true required: - self - current properties: self: $ref: '#/components/schemas/HRef' current: $ref: '#/components/schemas/HRef' next: $ref: '#/components/schemas/HRef' previous: $ref: '#/components/schemas/HRef' examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' HRef: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference PagingInfo: type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: $ref: '#/components/schemas/Links' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' 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. 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. 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. page: name: page in: query required: true schema: type: integer format: int32 minimum: 0 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: 1318joqblpp4e 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).' x-stoplight: id: s2ika6rltk5y6 query: name: query in: query required: false schema: type: string description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' x-stoplight: id: gupdb9kt30hfq 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).' x-stoplight: id: 4je9lwo02netu securitySchemes: auth_header: name: Authorization description: 'The word "Basic" followed by a space and your API Key, base64 encoded, which can be found [here](https://app.codat.io/developers/api-keys)' type: apiKey in: header