Person
A Person represents a natural person that can either be:
- An individual end-user you intend to onboard (for KYC).
- An Ultimate Beneficial Owner (UBO) of a company (for KYB).
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. |
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.
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.