Manage accounts

Manage Roots accounts by creating them for reviewed end customers and using account state and available balance to control downstream activity.

See API versions and Beta status before using this workflow in production.

Before you begin

• Complete the required end-customer onboarding and review steps.
• Store the Roots person ID for the account owner.
• Confirm the enabled currency and account product for your company.

Create an account

Create an account with POST /frontoffice/accounts.

{
  "person_id": "person_business_123",
  "currency": "USD"
}

The current schema returns the account, including its status, kind, current balance, available balance, and FBO details when applicable.

{
  "id": "account_123",
  "person_id": "person_business_123",
  "owner_name": "Acme Trading Ltd",
  "program_id": "program_123",
  "currency": "USD",
  "status": "pending",
  "kind": "virtual",
  "current_balance": 0,
  "available_balance": 0,
  "fbo_reference": "fbo_123",
  "fbo_title": "Roots FBO",
  "created_at": "2026-08-03T10:10:00Z"
}

Use account state safely

Do not treat account creation as permission to fund the account or create outgoing payments. Account activation depends on the applicable review and approval flow.

Before any dependent action:

1. Retrieve the latest account record.
2. Confirm that its status permits the action.
3. Check for holds or restrictions.
4. Use the available balance—not the current balance alone—to determine whether funds can be used.

Retrieve account activity

Use the account-level endpoints to plan retrieval of account activity:

• GET /frontoffice/accounts/{account_id}
• GET /frontoffice/accounts/{account_id}/transactions
• GET /frontoffice/accounts/{account_id}/payments

Store the Roots account ID with your own customer and ledger references to support reconciliation.

Next steps

• Manage counterparties before using an external payment destination.
• Create payments after the account and counterparty are eligible.
• Reconcile balances and payments to manage recorded and available funds.