Create a verification session

Create a verification session for one person. The response normally returns status AWAITING_INPUT. A status of CREATED means the setup did not finish; repeat the call with the same idempotency_key. A repeat with the same idempotency_key returns the stored session. A repeat with the same key but a different customer_reference or a different requirement set returns 422. Signa must be enabled for your business. Required scope: compliance-kyc:create.

POSTapi-prod.blaaiz.com/api/external/compliance/kyc/sessions

Authorization

oauth2ClientCredentials compliance-kyc:create

AuthorizationBearer <token>

Use your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.

In: header

Scope: compliance-kyc:create

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

customer_reference*string

Your own reference for the person you verify. Blaaiz returns it on the session and on the webhook.

Lengthlength <= 100

idempotency_key*string

Your key for this create. A repeat of the same key returns the stored session instead of a new one. The key is unique to your business and is never released.

Lengthlength <= 100

requirements*array<>

What the session must prove. Order does not matter, and a value may appear once. Supported sets: [DOCUMENTS, SELFIE, FACE_MATCH], [DOCUMENTS], [DOCUMENTS, SELFIE, FACE_MATCH, PROOF_OF_ADDRESS], [DOCUMENTS, PROOF_OF_ADDRESS], and [PROOF_OF_ADDRESS]. FACE_MATCH needs DOCUMENTS and SELFIE in the same set. Any other combination fails with 422, and the message names the supported sets.

Items1 <= items <= 4

fulfilment_mode?string

Who collects the input. HOSTED is available for [DOCUMENTS, SELFIE, FACE_MATCH], [DOCUMENTS, SELFIE, FACE_MATCH, PROOF_OF_ADDRESS], [DOCUMENTS, PROOF_OF_ADDRESS], and [PROOF_OF_ADDRESS]. HEADLESS is available for [DOCUMENTS], [DOCUMENTS, PROOF_OF_ADDRESS], and [PROOF_OF_ADDRESS]. A set that includes SELFIE is never HEADLESS, and a set of [DOCUMENTS] alone is never HOSTED. Omit the field to let Blaaiz select a mode that the set supports and your business is allowed to use.

Value in

"HOSTED"
"HEADLESS"

applicant?

Details you already hold about the person. Every field is optional.

Response Body

`application/json`

Create a verification session

curl --request POST \  --url 'https://example.com/api/external/compliance/kyc/sessions' \  --header 'Content-Type: application/json' \  --data '{  "customer_reference": "user_10482",  "idempotency_key": "kyc-user_10482-2026-08-29",  "requirements": [    "DOCUMENTS",    "SELFIE",    "FACE_MATCH"  ],  "fulfilment_mode": "HOSTED",  "applicant": {    "first_name": "Amara",    "last_name": "Okafor",    "dob": "1993-04-17",    "country": "NGA"  }}'

{  "message": "Verification session created successfully.",  "data": {    "id": "9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33",    "business_id": "9d4c4ec5-572d-49de-a362-f01ed09f2b1b",    "customer_reference": "user_10482",    "requirements": [      "DOCUMENTS",      "SELFIE",      "FACE_MATCH"    ],    "fulfilment_mode": "HOSTED",    "status": "AWAITING_INPUT",    "steps": {      "documents": "PENDING",      "selfie": "PENDING",      "proof_of_address": null    },    "rejection": null,    "expires_at": "2026-08-30T09:14:22.000Z",    "completed_at": null,    "created_at": "2026-08-29T09:14:22.000Z",    "verification_link": "https://verify.blaaiz.com/c/8Kq2rV5wZs1tYb7NfPjX0aLmC4hD6gEuR9oT3nQiWxs",    "link_expires_at": "2026-08-29T09:44:22.000Z"  }}