Onboard a business end customer

Prepare a business end customer for Roots review by creating its business record and linking the people who own or control it.

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

Before you begin

• Activate your Roots client before submitting end-customer data.
• Collect the business's identity, ownership, operational, and expected-activity information.
• Create records for each required associated person, such as a UBO (ultimate beneficial owner), director, control person, or authorized signatory.
• Collect the documents required for the business and its associated people.

1. Create the business person

Create the end customer with POST /frontoffice/persons. A Person is Roots' shared record for either a business or an individual. Create the business with person_type: "Business" and role: "Customer".

{
  "person_type": "Business",
  "role": "Customer",
  "external_person_id": "customer_acme_001",
  "business_name": "Acme Trading Ltd",
  "email": "[email protected]"
}

The current mock returns a person record with an initial status. Save the returned id; you use it when you attach associated people, documents, and later account records.

{
  "id": "person_business_123",
  "person_type": "Business",
  "role": "Customer",
  "status": "Inactive",
  "cleared": false,
  "block_reason": null,
  "external_person_id": "customer_acme_001",
  "business_name": "Acme Trading Ltd"
}

2. Add the business profile

Provide the fields Roots needs to assess the business before it enters review. The current schema includes business identity, addresses, financial profile, operational profile, and regulatory information.

At a minimum, prepare the following data for the production workflow:

• Legal and trading names, incorporation number, incorporation date, and incorporation jurisdiction.
• Registered and mailing addresses.
• Business type, legal structure, description, website, and contact details.
• Tax details and the primary source of funds.
• Expected transaction volume and value, account purpose, business jurisdictions, and send/receive jurisdictions.
• Regulatory status, authority, and registration details when the business is regulated.

The production requirements are conditional: Roots evaluates the entity type, jurisdiction, product, payment rail, and risk context. Do not assume that a field being optional in the current mock schema means it will be optional in production.

3. Create associated-person records

Create each individual linked to the business as a separate Person record. Use person_type: "Individual" and role: "Graph" for a person who is represented only through their relationship to the business.

{
  "person_type": "Individual",
  "role": "Graph",
  "external_person_id": "ubo_jordan_001",
  "first_name": "Jordan",
  "last_name": "Lee",
  "email": "[email protected]"
}

Save the associated person's id. You will pass it in the association request.

4. Link each associated person to the business

Send POST /frontoffice/persons/{person_id}/associations, replacing {person_id} with the business person's ID.

{
  "person_id": "person_individual_456",
  "role": "UBO",
  "ownership": 50
}

A successful response creates an active association.

{
  "id": "association_789",
  "person_id": "person_individual_456",
  "role": "UBO",
  "ownership": 50,
  "status": "Active"
}

The endpoint returns 400 when the linked person is not a graph person, 404 when the business does not exist, and 409 when the association already exists.

5. Upload documents and submit for review

The documentation context describes a production flow in which you upload business and associated-person documents, then submit a complete package for KYB (Know Your Business) review. The current API reference exposes a mocked document endpoint, but it does not yet define a submission endpoint or document request schema.

Prepare to submit documents such as:

• Formation and incorporation documents.
• Ownership breakdown or ownership chart.
• Proof of address, source of funds, and operations.
• Regulatory license or registration, if the business is regulated.

Roots validates completeness, screens the business and associated people, and evaluates risk before account issuance. An end customer must not transact while its review is pending, while an RFI is open, or when its status is restricted.

Understand expected outcomes

The planned onboarding workflow can produce these outcomes:

Next steps

• Create an account only after the production account flow and the required review and approval gates are complete.
• Create and screen counterparties before using them in payments.
• Design your integration to retain the Roots person ID and your external_person_id so you can reconcile asynchronous review updates.