Core concepts

Model Roots persons, reviews, accounts, counterparties, and payments so your integration can safely respond to compliance and transaction state changes.

See API versions and Beta status before using these object models in production.

Core objects

Roots uses a shared set of objects to represent an end customer, its compliance lifecycle, its accounts, and its payment activity.

Object	What it represents	How you use it
Client	Your organization as a direct Roots customer.	Your client must be active before it can submit end-customer data or use enabled capabilities.
Person	A business or individual record.	Create a business person for an end customer and individual graph persons for people linked to that business.
Association	A relationship between two persons.	Link a business to a UBO (ultimate beneficial owner), director, control person, or authorized signatory.
Identity	The latest structured information Roots holds about a person.	Provide complete, accurate information and supporting documents for review.
Review	A point-in-time compliance assessment of an identity.	Monitor its outcome and stop downstream activity when the review requires information, enhanced diligence, or manual assessment.
Account	A virtual account or wallet, depending on the product version.	Use account IDs for balances, transactions, and payment instructions after the account becomes active.
Counterparty	An external individual, business, or financial destination involved in a payment.	Create and screen the counterparty before using it for a payment.
Payment	A deposit, withdrawal, or internal transfer.	Treat its current status as the source of truth for processing and settlement.
RFI	A request for information.	Collect and submit the requested evidence; keep affected activity blocked until Roots resolves the request.

1. Build around the person and association model

Use a Person for both businesses and individuals. A business end customer uses the Customer role. An individual who exists only as part of a business ownership or control structure uses the Graph role.

Create an Association to make the relationship explicit. The current API schema supports Director, UBO, AuthorizedSignatory, and ControlPerson association roles.

Business person: Acme Trading Ltd (Customer)
  ├── Jordan Lee (Graph) — UBO, 50% ownership
  ├── Morgan Chen (Graph) — Director
  └── Taylor Patel (Graph) — AuthorizedSignatory

Keep your own external IDs alongside Roots person and association IDs. This lets you match an asynchronous review update to the right end customer and associated person.

2. Treat a review as a separate lifecycle

A review evaluates an identity at a particular time. The product model includes review types for client KYB, end-customer KYB, end-customer KYC, associated-person screening, counterparty screening, post-funding review, and periodic refresh.

A review can move through states such as CREATED, IN_PROGRESS, PASSED, FAILED, RFI_REQUIRED, EDD_REQUIRED, and REJECTED. The current mock API does not expose all of these states directly, so do not hard-code them as the complete production response contract.

Your integration should:

Submit complete data, documents, and associated-person information.
Wait for the review outcome before initiating dependent activity.
Route RFI_REQUIRED and EDD_REQUIRED outcomes to a human workflow.
Prevent onboarding or payment automation when a review is pending, failed, restricted, or escalated.
Re-check the linked person and account state after Roots resolves a review.

3. Separate account status from review status

An approved review does not necessarily mean an account is ready to transact. Accounts have their own operational lifecycle.

Account state	Meaning	Integration behavior
`PENDING_ISSUANCE`	Account creation has not completed.	Do not display account instructions or accept payment activity as available.
`ISSUED_DORMANT`	Account has been issued but is awaiting first funding and applicable review.	Do not assume funds are available or outgoing payments are enabled.
`ACTIVE`	Account can transact within its enabled capabilities and restrictions.	Retrieve account and payment state before initiating each action.
`ACTIVE_WITH_RESTRICTIONS`	Account remains open but has limited activity.	Enforce the restriction returned by Roots; do not infer allowed operations.
`ON_HOLD` or `BLOCKED`	Compliance or operational controls prevent affected activity.	Stop automated actions and follow the linked RFI or review process.
`CLOSED`	The account is no longer active.	Do not create new payment instructions against it.

The current mock account endpoint instead returns pending, active, or closed. Use the published reference as the authoritative schema for the environment you are integrating with.

4. Distinguish current and available balances

A current balance represents recorded funds. An available balance represents funds that can be used under the applicable account and compliance controls.

Incoming funds can remain unavailable while Roots completes required screening or reviews an exception. Outgoing payment requests can also lock funds while the payment is pending, so do not calculate spendable funds from current balance alone.

Use the balance values returned by Roots and treat the available balance as the limit for initiating a new payment.

5. Screen counterparties before payment

A counterparty starts as pending in the current mock API. In the planned workflow, Roots screens counterparties when they are created, when relevant details change, and at transaction time.

Only use counterparties that Roots reports as active. Handle pending or blocked counterparties as non-payable until the production API provides a cleared status.

6. Treat payment creation as the start of a lifecycle

A payment create response does not guarantee settlement. The current schema exposes Pending, Submitted, Settled, Failed, and Returned.

Payment state	Meaning	Integration behavior
`Pending`	Payment exists but is not settled.	Keep the instruction visible as in progress; do not report delivery.
`Submitted`	Payment has entered processing.	Continue monitoring for a terminal state.
`Settled`	Payment completed.	Reconcile the final amount, currency, and reference in your ledger.
`Failed`	Payment did not complete.	Investigate the cause before creating a replacement.
`Returned`	Payment was returned after processing started.	Reconcile the returned funds and create a new instruction only when appropriate.

A production payment can also be held while Roots completes required screening, validates missing information, or reviews an exception. Always retrieve the latest state rather than assuming the initial response is final.

Optional: Plan for first funding

The intended Roots workflow performs additional review after an account's first inbound funding event. A newly issued account can require a post-funding review before it becomes fully active.

Design for a delay between receiving an incoming payment event and having funds available. Do not release, transfer, or promise access to newly received funds until Roots reports that the applicable account and funds controls have cleared.

Next steps

Follow Onboard a business end customer to model businesses and associated people.
Follow Create accounts, counterparties, and payments to plan the operational sequence.
Follow Respond to RFIs and understand holds to handle blocked activity safely.