> ## 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. # Persons > Natural and legal parties that fuel onboarding applications A **person** (`per_...`) is a natural person (human) or legal person (company, trust, other entity). Persons are standalone until an [onboarding application](/docs/onboarding/applications) referencing them is approved. Every person is built from [claims](/docs/onboarding/claims), typed data points capturing identity, residence, ownership, PEP status, and so on. Every `POST /persons` must include at least the mandatory claim set for its `person_type`: | `person_type` | Mandatory claims | | ------------- | ---------------------------------- | | `natural` | `identity` + `contact_details` | | `legal` | `registration` + `contact_details` | Omitting any of these returns `400 invalid_request` with detail ` persons require claim types [...]; missing: [...]`. You can include additional claims in the same request (and usually will, to round out the person's profile). ## Natural vs. legal persons `person_type` determines which claim types are acceptable. | `person_type` | Represents | Example claim types | | ------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `natural` | A human | `identity`, `contact_details`, `nationalities`, `residence`, `tax_residencies`, `pep_status`, `employment`, `financial_profile` | | `legal` | A company, trust, partnership, or other legal entity | `registration`, `contact_details`, `lei`, `registered_address`, `business_nature`, `relationships` | `operating_address` is also a legal-person claim. You only add it when the legal owner's `registered_address` has `operating_address_is_same` set to `false`; see [conditional requirements](/docs/onboarding/applications#conditional-requirements). Legal persons declare counterparties (directors, shareholders, UBOs, trustees, signatories) via a [`relationships`](/docs/onboarding/claims#relationships) claim. Related persons must already exist. Claim types are enforced against `person_type`: mismatches on `POST /persons` or `POST /persons/{person_id}/claims` return `400 invalid_request`. See the [claim type reference](/docs/onboarding/claims#claim-type-reference). ## Creating a person `POST /persons` with `person_type` and a non-empty `claims` array. Creation is **atomic**: if any claim fails validation, nothing is persisted. ```python Python theme={"theme":"catppuccin-mocha"} import requests response = requests.post( "https://api.engine.usesophic.com/persons", headers={ "Authorization": "Bearer YOUR_ACCESS_TOKEN", "Content-Type": "application/json", }, json={ "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": "residence", "line1": "1 Example Street", "postal_code": "SW1A 1AA", "city": "London", "country_code": "GB", }, ], }, ) person = response.json() ``` ```javascript Node.js theme={"theme":"catppuccin-mocha"} const response = await fetch( "https://api.engine.usesophic.com/persons", { method: "POST", headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN", "Content-Type": "application/json", }, body: JSON.stringify({ 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: "residence", line1: "1 Example Street", postal_code: "SW1A 1AA", city: "London", country_code: "GB", }, ], }), } ); const person = await response.json(); ``` ```go Go theme={"theme":"catppuccin-mocha"} package main import ( "bytes" "encoding/json" "net/http" ) func main() { body, _ := json.Marshal(map[string]interface{}{ "person_type": "natural", "claims": []map[string]interface{}{ { "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": "residence", "line1": "1 Example Street", "postal_code": "SW1A 1AA", "city": "London", "country_code": "GB", }, }, }) req, _ := http.NewRequest("POST", "https://api.engine.usesophic.com/persons", bytes.NewBuffer(body)) req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN") req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() var person map[string]interface{} json.NewDecoder(resp.Body).Decode(&person) } ``` ```java Java theme={"theme":"catppuccin-mocha"} HttpClient client = HttpClient.newHttpClient(); String json = """ { "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": "residence", "line1": "1 Example Street", "postal_code": "SW1A 1AA", "city": "London", "country_code": "GB" } ] } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.engine.usesophic.com/persons")) .header("Authorization", "Bearer YOUR_ACCESS_TOKEN") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); ``` ```csharp C# theme={"theme":"catppuccin-mocha"} using var client = new HttpClient(); client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN"); var payload = new { person_type = "natural", claims = new object[] { new { claim_type = "identity", first_name = "Ada", last_name = "Lovelace", date_of_birth = "1985-12-10" }, new { claim_type = "contact_details", phone_number = "+447700900123", email = "ada@example.com" }, new { claim_type = "residence", line1 = "1 Example Street", postal_code = "SW1A 1AA", city = "London", country_code = "GB" } } }; var response = await client.PostAsJsonAsync( "https://api.engine.usesophic.com/persons", payload); ``` ### Response A successful request returns `201 Created`: ```json theme={"theme":"catppuccin-mocha"} { "id": "per_m4k7r9s2", "created_at": "2026-04-18T09:30:00Z", "modified_at": "2026-04-18T09:30:00Z", "person_type": "natural", "full_name": "Ada Lovelace", "claims": [ { "id": "clm_abc123", "created_at": "2026-04-18T09:30:00Z", "status": "pending", "claim_type": "identity", "first_name": "Ada", "last_name": "Lovelace", "date_of_birth": "1985-12-10" }, { "id": "clm_def456", "created_at": "2026-04-18T09:30:00Z", "status": "pending", "claim_type": "contact_details", "phone_number": "+447700900123", "email": "ada@example.com" }, { "id": "clm_ghi789", "created_at": "2026-04-18T09:30:00Z", "status": "pending", "claim_type": "residence", "line1": "1 Example Street", "line2": null, "line3": null, "district_county": null, "postal_code": "SW1A 1AA", "city": "London", "country_code": "GB" } ] } ``` | Field | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | The person's unique ID, prefix `per_`. | | `person_type` | `natural` or `legal`. | | `full_name` | Natural: `"{first_name} {last_name}"` from the identity claim. Legal: `entity_name` from registration, or empty. | | `claims` | The claims you provided. Each element carries `id`, `created_at`, `status: pending`, `claim_type`, and the fields defined for that `claim_type`. To get the full claim (with `person`, `lifecycle`, `verified_at`, `superseded_at`, `archived_at`) for a specific claim later, call [`GET /persons/{person_id}/claims/{claim_id}`](/api-reference/retrieve-a-person-claim). See [claim lifecycle](/docs/onboarding/claims#lifecycle). | Persons don't have their own status; lifecycle lives on claims. See [lifecycle](/docs/onboarding/claims#lifecycle). `POST /persons` doesn't de-duplicate retries. Record the returned `id` and reuse it on retries. ## Retrieving a person Use [`GET /persons/{id}`](/api-reference/retrieve-a-person) to fetch the person record. Claims aren't included; list them separately. ```bash theme={"theme":"catppuccin-mocha"} curl https://api.engine.usesophic.com/persons/per_m4k7r9s2 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` Use [`GET /persons/{person_id}/claims`](/api-reference/list-claims-for-a-person) to list the person's claims, filtered by `claim_type` or `status`. By default you get every row for the person (current and historical) newest-first. Pass `include_history=false` to collapse to just the current rows (`active` + `in_flight`) per type. See [listing and retrieving claims](/docs/onboarding/claims#listing-and-retrieving-claims). ```bash theme={"theme":"catppuccin-mocha"} curl "https://api.engine.usesophic.com/persons/per_m4k7r9s2/claims?status=verified" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ## Authorities When an application referencing a person is approved, that person becomes an **authority** on the resulting customer and accounts. | `authority_type` | Meaning | | ------------------- | ------------------------------------------------------ | | `owner` | The primary owner of the customer. | | `joint_owner` | A joint owner on a shared customer. | | `signatory` | Can sign on behalf of the customer but doesn't own it. | | `power_of_attorney` | Acts under a power of attorney arrangement. | | `trading` | Authorised to place trades on the customer's accounts. | List authorities per person with [`GET /persons/{id}/authorities`](/api-reference/list-authorities-for-a-person), or per customer with [`GET /customers/{id}/authorities`](/api-reference/list-authorities-for-a-customer). ## Legal persons and relationships Create one person for the legal entity and one for every director, shareholder, UBO, trustee, settlor, or authorised signatory. Then add a `relationships` claim on the legal person. ```json theme={"theme":"catppuccin-mocha"} { "person_type": "legal", "claims": [ { "claim_type": "registration", "legal_name": "Ada & Co Ltd", "registration_number": "12345678", "date_of_incorporation": "2020-06-01", "country_of_incorporation": "GB", "entity_type": "private_limited_company" }, { "claim_type": "relationships", "relationships": [ { "related_person": "per_ada", "relationship_type": "director", "appointment_date": "2020-06-01" }, { "related_person": "per_grace", "relationship_type": "shareholder", "ownership_percentage": "50.00" } ] } ] } ``` Related persons must already exist; an unknown `related_person` ID fails the request with `400` and nothing is persisted. See [claim types](/docs/onboarding/claims#relationships) for the full `relationships` schema.