Skip to main content
A person (per_...) is a natural person (human) or legal person (company, trust, other entity). Persons are standalone until an onboarding application referencing them is approved. Every person is built from 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_typeMandatory claims
naturalidentity + contact_details
legalregistration + contact_details
Omitting any of these returns 400 invalid_request with detail <person_type> persons require claim types [...]; missing: [...]. You can include additional claims in the same request (and usually will, to round out the person’s profile). person_type determines which claim types are acceptable.
person_typeRepresentsExample claim types
naturalA humanidentity, contact_details, nationalities, residence, tax_residencies, pep_status, employment, financial_profile
legalA company, trust, partnership, or other legal entityregistration, 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. Legal persons declare counterparties (directors, shareholders, UBOs, trustees, signatories) via a 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.

​
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. 
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()

​
Response

A successful request returns 201 Created: 
{
  "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"
    }
  ]
}
FieldDescription
idThe person’s unique ID, prefix per_.
person_typenatural or legal.
full_nameNatural: "{first_name} {last_name}" from the identity claim. Legal: entity_name from registration, or empty.
claimsThe 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}. See claim lifecycle.
Persons don’t have their own status — lifecycle lives on claims. See lifecycle.
POST /persons doesn’t de-duplicate retries. Record the returned id and reuse it on retries.

​
Retrieving a person

Use GET /persons/{id} to fetch the person record. Claims aren’t included — list them separately. 
curl https://api.engine.usesophic.com/persons/per_m4k7r9s2 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Use GET /persons/{person_id}/claims 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. 
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_typeMeaning
ownerThe primary owner of the customer.
joint_ownerA joint owner on a shared customer.
signatoryCan sign on behalf of the customer but doesn’t own it.
power_of_attorneyActs under a power of attorney arrangement.
tradingAuthorised to place trades on the customer’s accounts.
List authorities per person with GET /persons/{id}/authorities, or per customer with GET /customers/{id}/authorities. 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. 
{
  "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 for the full relationships schema.