> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talescria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List accounts

> Every account you hold in the key's environment, with its balances. Rows are sorted by currency.

An account that can't be shown accurately is still listed, with `status: "unresolved"` and a `reason`, and never carries an amount. Don't add unresolved rows into a total.

Requires the `accounts:read` scope.



## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/accounts
openapi: 3.1.0
info:
  title: Talescria API
  version: 1.0.0
  description: >-
    Accounts, recipients, payments, transfers between your accounts, payment
    links, customers and invoices. Authenticate with an access token from your
    OAuth client.
servers:
  - url: https://api.talescria.com
    description: Production (test and live keys)
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Your accounts and their balances.
  - name: Recipients
    description: People and businesses you pay, and where to pay them.
  - name: Payments
    description: Paying recipients, including across currencies.
  - name: Transfers
    description: Moving money between your own accounts.
  - name: Payment links
    description: Links anyone can open to pay you by card.
  - name: Customers
    description: People and businesses who pay you.
  - name: Invoices
    description: One-off invoices and recurring series.
paths:
  /v1/accounts:
    get:
      tags:
        - Accounts
      summary: List accounts
      description: >-
        Every account you hold in the key's environment, with its balances. Rows
        are sorted by currency.


        An account that can't be shown accurately is still listed, with `status:
        "unresolved"` and a `reason`, and never carries an amount. Don't add
        unresolved rows into a total.


        Requires the `accounts:read` scope.
      operationId: listAccounts
      responses:
        '200':
          description: >-
            The account's wallets. An empty `accounts` array means no wallets
            yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountsListing'
              examples:
                twoWallets:
                  summary: Two wallets, one with money
                  value:
                    merchantId: mch_01M2P8FSY2C8MHHH93W4ADPGG0
                    environment: test
                    accounts:
                      - status: ok
                        accountId: acct_01M2P8GPSHV33BTXWH3NSJ4MC2
                        name: Lagos collections
                        isDefault: true
                        currency: NGN
                        posted:
                          minorUnits: '0'
                          currency: NGN
                        pending:
                          minorUnits: '0'
                          currency: NGN
                        available:
                          minorUnits: '0'
                          currency: NGN
                      - status: ok
                        accountId: acct_01M2P8GP7RSDXN81CXRFM2HFV7
                        name: Operations
                        isDefault: true
                        currency: USD
                        deposit:
                          status: ready
                          scheme: faster_payments
                          fields:
                            - key: account_number
                              label: Account number
                              value: '12345678'
                            - key: sort_code
                              label: Sort code
                              value: 04-00-04
                        posted:
                          minorUnits: '125000'
                          currency: USD
                        pending:
                          minorUnits: '0'
                          currency: USD
                        available:
                          minorUnits: '125000'
                          currency: USD
                    totals:
                      - currency: NGN
                        accounts: 1
                        posted:
                          minorUnits: '0'
                          currency: NGN
                        pending:
                          minorUnits: '0'
                          currency: NGN
                        available:
                          minorUnits: '0'
                          currency: NGN
                      - currency: USD
                        accounts: 1
                        posted:
                          minorUnits: '125000'
                          currency: USD
                        pending:
                          minorUnits: '0'
                          currency: USD
                        available:
                          minorUnits: '125000'
                          currency: USD
                    unresolved: 0
                noWallets:
                  summary: A new account
                  value:
                    merchantId: mch_01M2P8FSY2C8MHHH93W4ADPGG0
                    environment: test
                    accounts: []
                    totals: []
                    unresolved: 0
                unresolved:
                  summary: An account that can't be shown right now
                  value:
                    merchantId: mch_01M2P8FSY2C8MHHH93W4ADPGG0
                    environment: test
                    accounts:
                      - status: unresolved
                        accountId: acct_01M2P8GP7RSDXN81CXRFM2HFV7
                        name: Operations
                        isDefault: true
                        currency: USD
                        reason: NOT_IN_LEDGER
                        detail: this account can't be read right now
                    totals: []
                    unresolved: 1
        '400':
          description: '`VALIDATION`: A field is missing or malformed. `message` says which.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            `UNAUTHENTICATED`: The access token is missing, expired or revoked.
            Get a new token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `ENVIRONMENT_UNAVAILABLE`: Live mode isn't available until your
            account is approved.


            `INSUFFICIENT_SCOPE`: Your API key lacks the scope this operation
            needs. The scope is named in `message` and the `WWW-Authenticate`
            header.


            `ENVIRONMENT_MISMATCH`: The request named a different environment
            from the key's.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`RATE_LIMITED`: Too many requests. Wait for `Retry-After` seconds.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: >-
            `MISCONFIGURED`: Something is wrong on our side. Contact support
            with the `x-request-id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: >-
            `UPSTREAM_ERROR`: A service we depend on answered unexpectedly.
            Retry, and contact support with the `x-request-id` if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: '`UPSTREAM_UNAVAILABLE`: Temporarily unavailable. Retry with backoff.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    AccountsListing:
      type: object
      required:
        - merchantId
        - environment
        - accounts
        - totals
        - unresolved
      properties:
        merchantId:
          type: string
        environment:
          type: string
          enum:
            - test
            - live
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/AccountRow'
        totals:
          type: array
          description: >-
            Per currency, what the resolved rows add up to (the roll-up with
            `include=below`).
          items:
            type: object
            properties:
              currency:
                type: string
              accounts:
                type: integer
              posted:
                $ref: '#/components/schemas/Money'
              pending:
                $ref: '#/components/schemas/Money'
              available:
                $ref: '#/components/schemas/Money'
        unresolved:
          type: integer
          description: Rows left out of `totals` because they didn't resolve.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Branch on this, not on `message`. See Errors.
            message:
              type: string
              description: For people. Wording can change.
    AccountRow:
      oneOf:
        - $ref: '#/components/schemas/AccountRowOk'
        - $ref: '#/components/schemas/AccountRowUnresolved'
      discriminator:
        propertyName: status
        mapping:
          ok: '#/components/schemas/AccountRowOk'
          unresolved: '#/components/schemas/AccountRowUnresolved'
    Money:
      type: object
      required:
        - minorUnits
        - currency
      properties:
        minorUnits:
          type: string
          pattern: ^-?\d+$
          description: Integer minor units as a string. Never a float.
          example: '125000'
        currency:
          type: string
          example: USD
    AccountRowOk:
      type: object
      required:
        - status
        - accountId
        - currency
        - isDefault
        - posted
        - pending
        - available
      properties:
        status:
          const: ok
        accountId:
          type: string
        name:
          type: string
          description: Your name for the account. Absent if it was opened without one.
        isDefault:
          type: boolean
          description: >-
            Whether an inbound checkout payment in this currency lands here.
            Exactly one account per currency has it.
        currency:
          type: string
        accountType:
          type: string
          enum:
            - checking
            - debit
            - operational
            - safeguard
          description: >-
            What the account is for. **Absent** for one opened before this field
            existed, unknown, which is not the same claim as `operational`, and
            the two must not be shown alike. Safeguarded funds are held under a
            different legal duty than operating cash.
        posted:
          $ref: '#/components/schemas/Money'
          description: Settled balance.
        pending:
          $ref: '#/components/schemas/Money'
          description: Reserved by outgoing payments still in flight.
        available:
          $ref: '#/components/schemas/Money'
          description: 'What can be spent: posted minus pending. Show this as the balance.'
        deposit:
          type: object
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - pending
                - ready
              description: >-
                `pending` means the account exists at the provider and nobody
                can send to it yet. `fields` is absent, not empty, "not yet" and
                "there are none" are different answers.
            scheme:
              type: string
              description: The rail these are for, faster_payments, sepa, ach, nip, erc20.
              example: faster_payments
            fields:
              type: array
              description: >-
                Ordered for display. A list rather than a shape because details
                differ per currency and rail: GBP is an account number and a
                sort code, EUR an IBAN and a BIC, a stablecoin account a wallet
                address. `key` is normalised where recognised so the UI can
                label it and attach a copy button; anything else arrives with
                the provider's own label rather than being dropped.
              items:
                type: object
                required:
                  - key
                  - label
                  - value
                properties:
                  key:
                    type: string
                    example: sort_code
                  label:
                    type: string
                    example: Sort code
                  value:
                    type: string
                    example: 04-00-04
    AccountRowUnresolved:
      type: object
      required:
        - status
        - accountId
        - currency
        - isDefault
        - reason
        - detail
      properties:
        status:
          const: unresolved
        name:
          type: string
          description: Your name for the account. Absent if it was opened without one.
        isDefault:
          type: boolean
          description: Whether an inbound checkout payment in this currency lands here.
        accountId:
          type: string
        currency:
          type: string
        reason:
          type: string
          enum:
            - NOT_IN_LEDGER
            - CURRENCY_MISMATCH
        detail:
          type: string
          description: For developers, not end users.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An access token (`at_test_…` or `at_live_…`) from `POST
        https://idp.talescria.com/oauth/token`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.