Skip to main content
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

1

Build the parties

Create a person for every party — the customer plus any directors, shareholders, or beneficial owners for a business — from a list of typed claims.
2

Submit the application

Submit a single onboarding application 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 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

ResourcePrefixCreated by
Personper_You, via POST /persons
Person claimclm_You, via POST /persons/{person_id}/claims
Onboarding applicationonba_You, via POST /onboarding-applications
Customercus_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.
1

Create the person with their claims

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.
2

Upload evidence files

Upload the passport and selfie via the Files API; hold onto the returned file IDs.
3

Submit the onboarding application

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"}
    ]
  }'
4

Wait for compliance review

You’ll get back status pending with no outcome yet. Poll GET /onboarding-applications/{id} 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. See required consents for the full breakdown.

​
Where to next

Persons

Natural and legal persons, built from claims.

Claims

Claim types, schemas, and lifecycle.

Applications

Authorities, consents, evidence, and duplicates.

Errors

Every validation error and how to fix it.