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'
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
'/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'
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
'/companies/{companyId}/connections/{connectionId}/data/banking-accounts/{accountId}':
get:
tags:
- Accounts
summary: Get account
operationId: get-account
description: Gets a specified bank account for a given company
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'
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'
'/companies/{companyId}/connections/{connectionId}/data/banking-transactionCategories':
get:
tags:
- Transaction categories
operationId: list-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'
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
description: Gets a list of hierarchical categories associated with a transaction for greater contextual meaning to transactionactivity.
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: Gets a specified bank transaction category for a given company
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'
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: Gets a list of transactions incurred by a bank account.
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
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
summary: List banking transactions
description: Gets a list of transactions incurred by a company across all bank accounts.
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Transactions'
examples: {}
'/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'
description: Gets a specified bank transaction for a given company
operationId: get-transaction
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
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.
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:
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.
It 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.
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 the source platform does not provide modification date information,
- For attachments, balance sheets, company information, and profit & loss reports.
In Codat's data model, dates and times are represented using the ISO 8601 standard.
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
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: '-modifiedDate'
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).'
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