Onboard a business end customer

Create a business person, link associated people, upload documents, and submit the onboarding record for Roots review.

See API availability before you use an onboarding workflow in production.

Before you begin

Obtain a bearer access token through Authentication.
Generate a new Idempotency-Key for each create, upload, association, and review-submission request.
Collect the business identity, mailing address, ownership structure, financial profile, operational profile, and required documents.

1. Create the business person

Create the business with POST /api/v1/client/persons.

Field	Type	Required	Description
`type`	string	Yes	Set to `business`.
`details`	object	Yes	Business identity information, including the legal name required by your program.
`mailing_address`	object	Yes	Business mailing address.
`registered_address`	object	No	Registered address when applicable.
`financial_profile`	object	No	Financial information required for review.
`operational_profile`	object	No	Expected activity and operational information required for review.

{
  "type": "business",
  "details": {
    "legal_name": "Acme Trading Ltd"
  },
  "mailing_address": {
    "line1": "1 Main Street",
    "city": "Singapore",
    "country": "SG"
  }
}

Save the returned id. Roots returns the person lifecycle fields review_stage, review_outcome, review_id, and onboarding_progress_pct with the record.

2. Create and link associated people

Create each associated person with POST /api/v1/client/persons, using type: "individual". Then link the person to the business with POST /api/v1/client/persons/{business_person_id}/associations.

Field	Type	Required	Values
`related_person_id`	string	Yes	ID of the associated person.
`role`	string	Yes	`BENEFICIAL_OWNER`, `AUTHORIZED_SIGNATORY`, or `DIRECTOR`.
`ownership_percentage`	integer	No	Ownership percentage when applicable.

{
  "related_person_id": "person_456",
  "role": "BENEFICIAL_OWNER",
  "ownership_percentage": 60
}

3. Upload documents

Upload each required document with POST /api/v1/client/persons/{person_id}/documents as multipart/form-data.

Form field	Type	Required	Values
`file`	binary	Yes	Document content.
`type`	string	Yes	`government_id`, `proof_of_address`, `articles_of_incorporation`, or `beneficial_ownership_certificate`.

Use GET /api/v1/client/persons/{person_id}/documents to list uploaded documents. Roots returns document metadata; retrieve document content only through the documented document-content endpoint and your authorized workflow.

4. Submit the onboarding record for review

Submit the completed person record with POST /api/v1/client/persons/{person_id}/review/submit. This request requires both bearer authentication and an idempotency key.

Retrieve the person again after submission. Use review_stage, review_outcome, and any associated compliance workflow to determine the next permitted action.

5. Gate dependent activity

Do not create an account merely because the person record exists. Create an account only after the current review result and any required bank approval permit the account workflow.

Next steps

Read Onboarding and review lifecycle for review outcomes.
Read Manage accounts when the person is eligible for an account.
Read Idempotency before retrying onboarding writes.