Persons

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_type`	Mandatory claims
`natural`	`identity` + `contact_details`
`legal`	`registration` + `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).

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

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();

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)
}

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<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

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:

{
  "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}`. 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_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.

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.

{
  "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.

Getting Started

Onboarding

Orders

Webhooks

Natural vs. legal persons

Creating a person

Response

Retrieving a person

Authorities

Legal persons and relationships

​Natural vs. legal persons

​Creating a person

​Response

​Retrieving a person

​Authorities

​Legal persons and relationships

Natural vs. legal persons

Creating a person

Response

Retrieving a person

Authorities

Legal persons and relationships