Quickstart

Authenticate to Roots UAT, create a business person, submit it for review, and retrieve the resulting record.

Before you begin

• Obtain a client operator email address and password.
• Generate a unique idempotency key for each write request.
• Set the UAT base URL:

https://api.uat.roots.finance

1. Sign in

Create a session with POST /api/v1/client/auth/login.

curl --request POST https://api.uat.roots.finance/api/v1/client/auth/login \
  --header "Content-Type: application/json" \
  --data '{
    "email": "[email protected]",
    "password": "<your-password>"
  }'

Save access_token from the response. Send it on subsequent client requests:

Authorization: Bearer <access-token>

2. Create a business person

Create a business person with POST /api/v1/client/persons. The published request requires type, details, and mailing_address.

curl --request POST https://api.uat.roots.finance/api/v1/client/persons \
  --header "Authorization: Bearer <access-token>" \
  --header "Idempotency-Key: <unique-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "business",
    "details": {
      "legal_name": "Acme Trading Ltd"
    },
    "mailing_address": {
      "line1": "1 Main Street",
      "city": "Singapore",
      "country": "SG"
    }
  }'

Save the returned person id. The response also provides review_stage, review_outcome, and onboarding_progress_pct.

3. Submit the person for review

Submit the person with POST /api/v1/client/persons/{person_id}/review/submit.

curl --request POST https://api.uat.roots.finance/api/v1/client/persons/<person-id>/review/submit \
  --header "Authorization: Bearer <access-token>" \
  --header "Idempotency-Key: <unique-key>"

The response returns the updated PersonDetail. Use its review_stage and review_outcome to determine whether you can continue.

4. Retrieve the latest person state

Retrieve the person with GET /api/v1/client/persons/{person_id} before you create an account.

curl https://api.uat.roots.finance/api/v1/client/persons/<person-id> \
  --header "Authorization: Bearer <access-token>"

Do not create an account or transfer until the review outcome and program approval permit the next action.

Next steps

• Follow Onboard a business end customer for documents and associated people.
• Read Manage accounts after the person is eligible.
• Read API conventions for bearer authentication, idempotency, pagination, and amount rules.