Person Verification Request Fields
Submit individual data for Person Verification. Zenoo accepts three tiers of data. More data improves screening accuracy and reduces false positives.
Tier Examples
Tier 1: Minimum
The bare minimum for a Person Verification. Returns basic screening results.
{
"first_name": "Jane",
"last_name": "Smith",
"country": "GB"
}
Tier 2: Standard
Adds date of birth, contact details, and address. Enables identity verification, phone/email checks, and accurate screening with far fewer false positives.
{
"first_name": "Jane",
"last_name": "Smith",
"country": "GB",
"date_of_birth": "1990-06-15",
"email": "jane.smith@example.com",
"phone": "+447700900123",
"address": "42 Baker Street",
"city": "London",
"postal_code": "NW1 6XE"
}
Tier 3: Full
Maximum data for highest accuracy. Adds nationality, document preference, and an external reference for idempotency.
{
"first_name": "Jane",
"last_name": "Smith",
"country": "GB",
"date_of_birth": "1990-06-15",
"email": "jane.smith@example.com",
"phone": "+447700900123",
"address": "42 Baker Street",
"city": "London",
"postal_code": "NW1 6XE",
"nationality": "GB",
"document_type": "passport",
"external_reference": "APP-2026-0123"
}
Field Reference
| Field | Type | Required | Tier | Description |
|---|
first_name | string | Yes | Minimum | Individual’s first name |
last_name | string | Yes | Minimum | Individual’s last name |
country | string | Yes | Minimum | Country of residence. ISO 3166-1 alpha-2 code (e.g., GB, US) |
date_of_birth | string | No | Standard | Date of birth. ISO 8601 format: YYYY-MM-DD. Strongly recommended for screening accuracy |
email | string | No | Standard | Email address. Triggers email verification check |
phone | string | No | Standard | Phone number in E.164 format (e.g., +447700900123). Triggers phone verification |
address | string | No | Standard | Street address |
city | string | No | Standard | City |
postal_code | string | No | Standard | Postal or ZIP code |
nationality | string | No | Full | Nationality. ISO 3166-1 alpha-2 code |
document_type | string | No | Full | Preferred document type for verification. See accepted values below |
external_reference | string | No | Full | Your internal reference ID. Enables idempotency and correlation |
Document Types
When you specify document_type, the verification UI prompts the user with that document type first. The user can still select a different type if needed.
| Value | Description |
|---|
passport | National passport |
national_id | Government-issued national ID card |
driving_licence | Driving licence with photo |
document_type is omitted, the user chooses from all available options.
- Phone numbers. Use E.164 format: a
+ followed by the country code and number with no spaces or dashes. Examples: +447700900123 (UK), +12025551234 (US), +353861234567 (IE).
- Country codes. Always use ISO 3166-1 alpha-2 codes:
GB (not UK), US, DE, FR.
- Dates. Use ISO 8601 format:
YYYY-MM-DD. Example: 1990-06-15.
Date of birth impact. For screening, date_of_birth reduces false positives by 80-95% on common names. If you only provide one optional field, make it the date of birth.
external_reference twice, Zenoo returns the existing case tokens without creating a duplicate. Always use external references in production for idempotency.
Sync vs Async
Person Verification supports two execution models:
Async (user-facing). Use the /init endpoint for flows that require document capture and biometric verification. The user interacts with a verification UI.
POST /api/gateway/execute/{project_hash}/kyc/init
/api endpoint with the X-SYNC-TIMEOUT header for database lookups, phone verification, and screening when you already have the user’s data.
POST /api/gateway/execute/{project_hash}/kyc/api
X-SYNC-TIMEOUT: 30000
