API availability

Use this page to determine whether a Roots API resource is ready for your environment and which parts of its production contract you must confirm.

⚠️
Beta API: Roots is actively developing the API. Confirm the released contract and enabled capabilities with Roots before you process live funds.

Environments

Use the UAT base URL for the currently documented API:

https://api.uat.roots.finance

Availability matrix

Resource	Status	Authentication required today	Current Beta contract	Target production contract — confirm in API reference
Front-office authentication	Live	No published request-authentication requirement	Login, logout, and current-session endpoints are documented.	Session persistence and production authentication behavior.
Front-office users	Live	Confirm in API reference	List and create company users.	Production authorization and error behavior.
API keys	Live	Confirm in API reference	Create, list, and revoke company keys. The key secret is shown once at creation.	The request header or credential pattern for using an API key is not yet published.
Persons	Beta (mocked)	No	Create, retrieve, and update individual and business persons.	Required onboarding fields, document flow, submission flow, review outcomes, and production authorization.
Associations	Beta (mocked)	No	Link graph persons to a business as `Director`, `UBO`, `AuthorizedSignatory`, or `ControlPerson`.	Production validation and review dependencies.
Documents	Beta (mocked)	No	Document resource endpoints are listed.	Upload schema, accepted document types, review behavior, and retrieval authorization.
Accounts	Beta (mocked)	No	Create and retrieve accounts. Current states are `pending`, `active`, and `closed`.	Issuance and activation rules; states including `PENDING_ISSUANCE`, `ISSUED_DORMANT`, `ACTIVE`, `ACTIVE_WITH_RESTRICTIONS`, `ON_HOLD`, `BLOCKED`, and `CLOSED`.
Counterparties	Beta (mocked)	No	Create, retrieve, update, and list counterparties. Current states are `Pending`, `Active`, and `Blocked`.	Required screening data, update and re-screening behavior, and enabled payment rails.
Payments	Beta (mocked)	No	Create and list payments. Current states are `Pending`, `Submitted`, `Settled`, `Failed`, and `Returned`.	Idempotency, limits, error contract, settlement events, returns, and production authorization.
Requests and RFIs	Beta (mocked)	No	List requests and person requests.	Response endpoint, document-submission behavior, deadlines, notifications, and linked holds.
Trades	Beta (mocked)	No	Create and list USD/USDC trades.	Product availability, pricing, settlement behavior, and production authorization.
Webhooks and events	Planned	—	No event, registration, signature, retry, ordering, or replay contract is published.	Confirm the complete event-delivery contract before building a receiver.

Current and target lifecycle states

Accounts

Current (Beta)	Target (production)	Integration behavior
`pending`	`PENDING_ISSUANCE` or `ISSUED_DORMANT`	Do not treat a created account as ready for funding or outgoing payments.
`active`	`ACTIVE` or `ACTIVE_WITH_RESTRICTIONS`	Retrieve the latest account state and enforce returned restrictions.
`closed`	`CLOSED`	Do not create new payment instructions against the account.
—	`ON_HOLD` or `BLOCKED`	Stop affected automation and follow the linked review or RFI flow.

Payments

Current (Beta)	Target (production)	Integration behavior
`Pending`	A payment exists but is not final.	Keep the instruction in progress. Do not report delivery.
`Submitted`	A payment has entered processing.	Continue monitoring for a terminal state.
`Settled`	A payment has completed.	Reconcile the final result in your ledger.
`Failed`	A payment did not complete.	Reconcile before creating a replacement.
`Returned`	A payment was returned after processing began.	Reconcile returned funds before creating a replacement.
—	Held or pending bank decision	Keep affected funds and automation blocked until Roots reports an authorized outcome.

Target schema — confirm in API reference

The following design expectations are documented as target behavior, not as a released API contract:

Production account state and restriction detail.
Payment idempotency and safe retry behavior.
API-key request authentication header or credential pattern.
Webhook registration, event payloads, signatures, delivery retries, ordering, and replay.
RFI response and document-submission operations.
Deterministic sandbox scenarios that produce compliance or payment outcomes.

Do not implement these details until Roots publishes them in the API reference.

Amounts and precision

The current payment schema accepts amount as a JSON number. For example:

{
  "amount": 1250.5,
  "currency": "USD"
}

Use the exact decimal value returned by Roots when you reconcile a payment. Do not assume a minor-unit integer representation, an implicit rounding mode, or a supported decimal scale. Confirm currency precision and rounding behavior in the production API contract before processing live funds.

Production safeguards

Before enabling a workflow, confirm that Roots has enabled the applicable product, currency, payment rail, jurisdiction, and production capability for your company.

Your integration must also:

Treat every created account, counterparty, review, and payment as non-final until its current state permits the next action.
Use available balance—not current balance alone—to determine whether funds can be used.
Stop automated activity for an RFI, hold, restriction, blocked state, or non-terminal payment state.
Store Roots IDs and your own external references for reconciliation.
Verify released behavior in UAT before enabling production money movement.

Next steps

Follow Quickstart to create a front-office session and API key.
Read Core concepts to understand Roots objects and lifecycles.
Use Production readiness before enabling a live integration.
Review the API reference for the current schema.