> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engine.usesophic.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Onboard customers through persons, claims, and onboarding applications
Onboard a customer by describing the parties involved as **persons** and **claims**, then submitting an **onboarding application** that ties them together.
## The two-phase flow
Create a [person](/docs/onboarding/persons) for every party (the customer plus any directors, shareholders, or beneficial owners for a business) from a list of typed [claims](/docs/onboarding/claims).
Submit a single [onboarding application](/docs/onboarding/applications) referencing those persons as **authorities**, attaching per-person **consents** and **evidence files**.
We validate synchronously against the customer type's required claims, evidence, and consents. If it passes, the application is persisted in `pending` for compliance review.
## Persons vs. customers
A **person** (`per_...`) is a party (natural or legal) that you create. A [customer](/api-reference/retrieve-a-customer) is formed once an application is approved, establishing an active relationship with us; your persons are granted the requested authority over the customer and are linked to any provisioned accounts.
You don't create customers directly. Submit an application and we provision the customer and accounts on approval.
## What's in scope
| Resource | Prefix | Created by |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------- |
| Person | `per_` | You, via [`POST /persons`](/api-reference/create-a-person) |
| Person claim | `clm_` | You, via [`POST /persons/{person_id}/claims`](/api-reference/create-a-claim-for-a-person) |
| Onboarding application | `onba_` | You, via [`POST /onboarding-applications`](/api-reference/submit-an-onboarding-application) |
| Customer | `cus_` | Us, after application approval |
## A complete example
Individual end-to-end. For a business, create a person for the legal entity plus each director / shareholder, and include a `relationships` claim on the legal person.
```bash theme={"theme":"catppuccin-mocha"}
curl -X POST https://api.engine.usesophic.com/persons \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"person_type": "natural",
"claims": [
{"claim_type": "identity", "first_name": "Ada", "last_name": "Lovelace", "date_of_birth": "1985-12-10"},
{"claim_type": "contact_details", "phone_number": "+447700900123", "email": "ada@example.com"},
{"claim_type": "nationalities", "nationalities": [{"country_code": "GB", "basis": "birth"}]},
{"claim_type": "residence", "line1": "1 Example Street", "postal_code": "SW1A 1AA", "city": "London", "country_code": "GB"},
{"claim_type": "tax_residencies", "tax_residencies": [{"country_code": "GB", "tin": "QQ123456C"}]},
{"claim_type": "fatca_status", "is_us_person": false},
{"claim_type": "pep_status", "is_pep": false, "has_pep_association": false},
{"claim_type": "employment", "employment_status": "employed", "industry": "technology"},
{"claim_type": "financial_profile", "annual_income_eur": "50k_100k", "income_sources": ["salary"], "net_worth_eur": "100k_250k", "wealth_sources": ["savings"]},
{"claim_type": "investment_experience", "has_prior_experience": true, "asset_classes": ["equities"]},
{"claim_type": "expected_activity", "funding_currency": "EUR", "asset_classes": ["equities"], "annual_transactions": "1_10", "investment_amount": "lt_50k"}
]
}'
```
Keep the returned `id`; you'll reference it in the application.
Upload the passport and selfie via the [Files API](/api-reference/create-a-file); hold onto the returned file IDs.
```bash theme={"theme":"catppuccin-mocha"}
curl -X POST https://api.engine.usesophic.com/onboarding-applications \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer_type": "individual",
"authorities": [
{"person": "per_abc123", "authority_type": "owner"}
],
"consents": [
{"person": "per_abc123", "consent_type": "terms_of_service", "legal_document_version": "legal_doc_ver_tos_v3", "consented_at": "2026-04-18T09:30:00Z"},
{"person": "per_abc123", "consent_type": "investment_service_agreement", "legal_document_version": "legal_doc_ver_isa_v1", "consented_at": "2026-04-18T09:30:00Z"},
{"person": "per_abc123", "consent_type": "risk_disclosures", "legal_document_version": "legal_doc_ver_risk_v2", "consented_at": "2026-04-18T09:30:00Z"},
{"person": "per_abc123", "consent_type": "conflicts_of_interest_policy", "legal_document_version": "legal_doc_ver_coi_v1", "consented_at": "2026-04-18T09:30:00Z"},
{"person": "per_abc123", "consent_type": "complaints_handling_policy", "legal_document_version": "legal_doc_ver_complaints_v1","consented_at": "2026-04-18T09:30:00Z"},
{"person": "per_abc123", "consent_type": "client_assets_safeguarding_policy", "legal_document_version": "legal_doc_ver_cass_v1", "consented_at": "2026-04-18T09:30:00Z"},
{"person": "per_abc123", "consent_type": "investor_compensation_fund_policy", "legal_document_version": "legal_doc_ver_icf_v1", "consented_at": "2026-04-18T09:30:00Z"},
{"person": "per_abc123", "consent_type": "order_execution_policy", "legal_document_version": "legal_doc_ver_oep_v1", "consented_at": "2026-04-18T09:30:00Z"},
{"person": "per_abc123", "consent_type": "data_accuracy", "consented_at": "2026-04-18T09:30:00Z"}
],
"evidence": [
{"person": "per_abc123", "evidence_type": "identity_document", "document_type": "passport", "file": "fil_passport"},
{"person": "per_abc123", "evidence_type": "selfie", "file": "fil_selfie"},
{"person": "per_abc123", "evidence_type": "proof_of_address", "document_type": "utility_bill", "file": "fil_poa"}
]
}'
```
You'll get back `status` `pending` with no `outcome` yet. Poll [`GET /onboarding-applications/{id}`](/docs/onboarding/applications#retrieving-an-application) for updates; the customer and accounts appear once compliance approves.
Every consent here except `data_accuracy` references a `legal_document_version`. `data_accuracy` is an attestation; omit the field. List valid document versions via the [legal document versions endpoint](/api-reference/list-versions-of-a-legal-document). See [required consents](/docs/onboarding/applications#required-consents) for the full breakdown.
## Where to next
Natural and legal persons, built from claims.
Claim types, schemas, and lifecycle.
Authorities, consents, evidence, and duplicates.
Every validation error and how to fix it.