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
      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'
      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
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionCategory'
      deprecated: true
      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
      operationId: list-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.
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
  '/companies/{companyId}/data/banking-transactions':
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      deprecated: true
      x-speakeasy-ignore: true
      tags:
        - Transactions
      operationId: list-bank-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.
  '/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
      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 <a class="external" href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 standard</a>. 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 <a class="external" href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 standard</a>.
    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 <a class="external" href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 standard</a>.
    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