Manage accounts

Create and retrieve Roots accounts after an end customer completes the required review and approval gates.

See API availability before you use account operations in production.

Before you begin

Retrieve the latest person record and confirm its review outcome permits account creation.
Obtain a bearer access token.
Generate an Idempotency-Key for account creation.

Create an account

Create an account with POST /api/v1/client/accounts.

Field	Type	Required	Description
`owner_person_id`	string	Yes	ID of the person who owns the account.

{
  "owner_person_id": "person_123"
}

The response includes account identity, status, FBO information, lifecycle timestamps, and balance buckets.

{
  "id": "acct_123",
  "owner_person_id": "person_123",
  "kind": "virtual",
  "currency": "USD",
  "fbo_reference": "acct_123",
  "fbo_title": "Roots Technologies FBO Acme Trading Ltd",
  "status": "active",
  "created_at": "2026-08-10T12:00:00Z",
  "active_at": "2026-08-10T12:00:00Z",
  "closed_at": null,
  "balance": {
    "available": "0",
    "payin_pending_total": "0",
    "payout_pending_total": "0",
    "restricted_compliance_total": "0",
    "restricted_legal_total": "0"
  }
}

Read account balances

All balance values are decimal strings in minor units of the account currency. For USD, "5000" represents 5,000 cents, or USD 50.00.

Balance bucket	Meaning
`available`	Funds available for new activity.
`payin_pending_total`	Incoming funds that remain pending.
`payout_pending_total`	Funds committed to pending outgoing transfers.
`restricted_compliance_total`	Funds restricted by compliance controls.
`restricted_legal_total`	Funds restricted by legal controls.

Use only balance.available when you evaluate a new transfer amount.

Retrieve and close accounts

Use these endpoints to manage the account lifecycle:

GET /api/v1/client/accounts/{account_id} retrieves the latest account state and balances.
GET /api/v1/client/accounts lists accounts with owner_person_id_filter, status_filter, page, and page_size.
POST /api/v1/client/accounts/{account_id}/close closes an account when the current lifecycle permits closure.

Next steps

Read Manage counterparties before creating a withdrawal transfer.
Read Create transfers to move available funds.
Read Reconcile balances and transfers to reconcile balance buckets.