List accounts

Returns accounts belonging to one customer or legal entity.

GET/accounts

Request

curl -X GET "<BASE_URL>/accounts" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response · 200

{
  "accounts": [
    {
      "id": "8d6907d9-f5db-47ed-a55d-f4a87e120d0c",
      "ownerId": "customer_123",
      "currency": "USD",
      "balanceMinor": 125000,
      "status": "active"
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjUwfQ"
}

Authorization

OAuth scope: accounts.readThe access token must carry this scope.
Action: listAccounts

Headers

AuthorizationstringRequired
OAuth 2.0 client-credentials flow for machine workloads.
X-Request-IduuidOptional
UUID unique to this HTTP request. The gateway echoes a valid caller-supplied value or generates one when the header is omitted. The resulting value is returned in X-Request-Id and structured error responses.

Path and query parameters

ownerIdstringRequired
Non-empty identifier of the customer or legal entity whose accounts are returned.
pageSizeintegerOptional
Maximum number of resources to return.
pageTokenstringOptional
Opaque continuation token from a previous response.

Request body

This endpoint takes no request body.

Response

Status 200. Accounts returned successfully.

accountsarray of objectRequired
Accounts belonging to the requested owner; empty when no accounts match.
5 child fields
- balanceMinorintegerRequired
  Available balance expressed as an integer in the currency's minor unit.
- currencystringRequired
  Three-letter ISO 4217 settlement currency code.
  pattern ^[A-Z]{3}$
- iduuidRequired
  Stable account identifier.
- ownerIdstringRequired
  Customer or legal-entity identifier that owns the account.
  minimum length 1
- statusenumRequired
  Current account lifecycle state.
  Allowed values
  pending
  active
  frozen
  closed
nextPageTokenstringOptional
Opaque continuation token present only when another page is available. Send it unchanged as pageToken with the same query parameters.

Errors

Every error carries an HTTP status. Where it also carries a code, branch on the code, not on the message.

400INVALID_ARGUMENTThe request is malformed.
401UNAUTHENTICATEDAuthentication failed.
403PERMISSION_DENIEDThe principal is not authorized for this operation.
429RESOURCE_EXHAUSTEDA rate or concurrency limit was exceeded.
503UNAVAILABLEThe service is temporarily unavailable.