Person

A Person represents a natural person - an individual end-user you intend to onboard to the platform via KYC Onboarding.

Not for corporate representatives

Representatives, UBOs, and Business Contacts of a corporate are not Persons - they are Individual entities linked to a Corporate. See Corporate & Individuals.

This page covers how to create a person, required fields, and validation rules.

---

Creating a Person

Endpoint: POST /persons

Request Body

Send a JSON object with the following fields:

Field	Type	Required	Notes
external_id	String	Yes	Your reference ID in your own system (e.g., UUID).
first_name	String	Yes
middle_name	String	No	Optional.
last_name	String	Yes
nationality	String	Yes	ISO 3166-1 alpha-3 (e.g., DEU).
other_nationalities	List[String]	No	Array of ISO 3166-1 alpha-3 codes.
gender	Integer	Yes	ISO/IEC 5218: 0 (unknown), 1 (male), 2 (female), 9 (not specified).
birth_country	String	Yes	ISO 3166-1 alpha-3 (e.g., DEU).
birth_place	String	Yes	City/place of birth.
birth_date	Date	Yes	Format: YYYY-MM-DD.
street_name	String	Yes	Address street name.
street_number	String	Yes	Address street number.
city	String	Yes
postal_code	String	Yes
region	String	No	Region or State.
country	String	Yes	ISO 3166-1 alpha-3 (e.g., DEU).
phone	String	Yes	E.164 format (e.g., +49301234567).
email	String	Yes	User's email address.
tax_identification_number	String	Yes	Tax ID.
tax_country	String	Yes	ISO 3166-1 alpha-3.

Validation Rules

Person creation is validated on submission:

Rule	Response
external_id, email, and phone must each be unique across all persons.	409 Conflict, stating which field is already in use.
The address country must be supported by the platform.	422: "Country of the address <country> is not supported."
The person must be at least 18 years old (birth_date).	422 validation error.

Example Request

View cURL Request

curl -X POST https://<kyc_domain>/api/v1/persons \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "AA55-N84G-XFRE-CKNA",
    "first_name": "John",
    "middle_name": "Damian",
    "last_name": "Smith",
    "nationality": "DEU",
    "other_nationalities": ["GBR", "POL"],
    "gender": 1,
    "birth_country": "POL",
    "birth_place": "Szczebrzeszyn",
    "birth_date": "1974-09-17",
    "street_name": "Main street",
    "street_number": "34b",
    "city": "Berlin",
    "postal_code": "10317",
    "region": "Brandenburg",
    "country": "DEU",
    "phone": "+4930901820",
    "email": "john.smith@test.com",
    "tax_identification_number": "123456789",
    "tax_country": "DEU"
  }'

Example Response

View JSON Response

{
  "id": "44907951-1825-4a91-b1c8-f84d708a22e3",
  "external_id": "AA55-N84G-XFRE-CKNA",
  "first_name": "John",
  "middle_name": "Damian",
  "last_name": "Smith",
  "nationality": "DEU",
  "other_nationalities": ["GBR", "POL"],
  "gender": 1,
  "birth_country": "POL",
  "birth_place": "Szczebrzeszyn",
  "birth_date": "1974-09-17",
  "street_name": "Main street",
  "street_number": "34b",
  "city": "Berlin",
  "postal_code": "10317",
  "region": "Brandenburg",
  "country": "DEU",
  "phone": "+4930901820",
  "email": "john.smith@test.com",
  "tax_identification_number": "123456789",
  "tax_country": "DEU",
  "offboarded_at": null,
  "deleted_at": null,
  "created_at": "2024-09-03T14:55:26.346500Z",
  "updated_at": null
}

---

Listing Persons

Endpoint: GET /persons

Retrieves a paginated list of all created persons.

---

Getting a Person

Endpoint: GET /persons/{person_id}

Retrieves details for a specific person entity.

---

Getting a Person by External ID

Endpoint: GET /persons/external/{external_id}

Retrieves a person using the external_id you supplied at creation.

---

Listing a Person's Locks

Endpoint: GET /persons/{person_id}/locks

Retrieves a paginated list of the account locks applied to the person. Lock types are funding, trading, and withdrawal; filter with the optional status query parameter (active, released, deactivated, archived).

Locks are applied and released by compliance workflows, announced via the applyFundingLock/releaseFundingLock (and trading/withdrawal) webhook events.

---

Triggering Entitlements

Creating a person does not automatically start onboarding.

Action Required

To begin the KYC process, you must trigger the specific entitlement for this Person ID.

Trigger Entitlement →