KYZ API Reference
Know Your Zone — identity verification with liveness detection, document scanning, and flexible hosted or API-native flows.
https://api.aamos.ai/v1/kyz/Verification Flows
KYZ supports two verification flows. Choose based on your integration needs:
Hosted Flow
Redirect your user to a AAMOS-hosted verification page. No frontend work required. Best for quick integration and compliance.
API Flow
Submit documents and selfies programmatically via multipart upload. Full control over UX. Best for custom verification experiences.
POST /v1/kyz/sessions
Create a new verification session. Returns a session ID and, for hosted flow, a URL to redirect the user to.
Request — application/json
| Field | Type | Required | Description |
|---|---|---|---|
| user_ref | string | Required | Your internal user identifier. Used to correlate results back to your system. |
| flow | string | Required | Verification flow: hosted or api. |
| redirect_url | string | Optional | Where to redirect after hosted flow completes. Required when flow=hosted. |
| webhook_url | string | Optional | Receive a POST notification when verification is complete. |
Example — Hosted Flow
curl -X POST https://api.aamos.ai/v1/kyz/sessions \ -H "Authorization: Bearer ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "user_ref": "user_123456", "flow": "hosted", "redirect_url": "https://your-app.example.com/verification-complete", "webhook_url": "https://your-app.example.com/hooks/kyz" }'
Response — 201 Created
{
"session_id": "kyz_5e2a8f1c7d",
"hosted_url": "https://verify.aamos.ai/kyz_5e2a8f1c7d",
"expires_at": "2025-01-15T11:00:00Z"
}
For hosted flow, redirect the user to hosted_url. The session expires after 30 minutes.
GET /v1/kyz/sessions/:session_id
Retrieve the current status and result of a verification session.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| session_id | string | The session ID returned by POST /v1/kyz/sessions. |
curl https://api.aamos.ai/v1/kyz/sessions/kyz_5e2a8f1c7d \ -H "Authorization: Bearer ak_live_YOUR_KEY"
Response — 200 OK
{
"session_id": "kyz_5e2a8f1c7d",
"status": "approved",
"decision": "approved",
"confidence": 0.97,
"liveness": true,
"document_country": "SE",
"document_type": "passport",
"completed_at": "2025-01-15T10:45:00Z"
}
Session Status Values
| Status | Description |
|---|---|
| pending | Session created, awaiting user action. |
| in_progress | User has started verification. |
| processing | Documents submitted, verification in progress. |
| approved | Verification successful. |
| rejected | Verification failed — document invalid, liveness failure, or fraud signal. |
| expired | Session expired before completion. |
POST /v1/kyz/sessions/:session_id/submit
Submit identity documents and selfie for API-flow verification. Only available when the session was created with flow: "api".
403 Forbidden for sessions created with flow: "hosted".Request — multipart/form-data
| Parameter | Type | Required | Description |
|---|---|---|---|
| id_front | file | Required | Front of the identity document. JPEG or PNG. Max 10 MB. |
| id_back | file | Optional | Back of the identity document. Required for most national ID cards. |
| selfie | file | Required | Live selfie photo for liveness and biometric matching. JPEG or PNG. |
Example Request
curl -X POST https://api.aamos.ai/v1/kyz/sessions/kyz_5e2a8f1c7d/submit \ -H "Authorization: Bearer ak_live_YOUR_KEY" \ -F "id_front=@/path/to/passport_front.jpg" \ -F "id_back=@/path/to/passport_back.jpg" \ -F "selfie=@/path/to/selfie.jpg"
Response — 202 Accepted
{
"session_id": "kyz_5e2a8f1c7d",
"status": "processing",
"message": "Documents received. Verification will complete in 10-30 seconds."
}
Poll GET /v1/kyz/sessions/:session_id or wait for your webhook to receive the final result.