curl --request POST \
  --url https://api-prod.blaaiz.com/api/external/compliance/kyc/sessions \
  --header 'Authorization: Bearer <token>' \
  --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": "BLAAIZ_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": "BLAAIZ_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": null,
    "link_expires_at": null
  }
}

{
  "message": "Invalid or missing access token"
}

{
  "message": "The Merchant KYC feature is not enabled for this business.",
  "status": 403
}

{
  "message": "Too many open verification sessions; complete, cancel, or let existing sessions expire."
}

Verification sessions

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. Merchant KYC must be enabled for your business. Required scope: compliance-kyc:create.

POST

api

external

compliance

kyc

sessions

curl --request POST \
  --url https://api-prod.blaaiz.com/api/external/compliance/kyc/sessions \
  --header 'Authorization: Bearer <token>' \
  --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": "BLAAIZ_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": "BLAAIZ_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": null,
    "link_expires_at": null
  }
}

{
  "message": "Invalid or missing access token"
}

{
  "message": "The Merchant KYC feature is not enabled for this business.",
  "status": 403
}

{
  "message": "Too many open verification sessions; complete, cancel, or let existing sessions expire."
}

Authorizations

Authorization

string

header

required

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

Body

application/json

customer_reference

string

required

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

Maximum string length: 100

idempotency_key

string

required

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.

Maximum string length: 100

requirements

enum<string>[]

required

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.

Required array length: 1 - 4 elements

Available options:

DOCUMENTS,

SELFIE,

FACE_MATCH,

PROOF_OF_ADDRESS

fulfilment_mode

enum<string>

Who collects the input. Omit it to take the default for the requirement set: SUMSUB_HOSTED for [DOCUMENTS, SELFIE, FACE_MATCH], HEADLESS for [DOCUMENTS], and SUMSUB_HOSTED for every set that includes PROOF_OF_ADDRESS. BLAAIZ_HOSTED is available for [DOCUMENTS, SELFIE, FACE_MATCH] and for every set that includes PROOF_OF_ADDRESS. HEADLESS is available for [DOCUMENTS, PROOF_OF_ADDRESS] and [PROOF_OF_ADDRESS], but never for a set that includes SELFIE.

Available options:

SUMSUB_HOSTED,

BLAAIZ_HOSTED,

HEADLESS

applicant

object

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

Show child attributes

Response

Verification session created successfully.

message

string

required

data

object

required

Show child attributes