curl --request POST \
  --url https://api-prod.blaaiz.com/api/external/compliance/kyc/sessions/{sessionId}/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "passport-front.jpg",
  "content_type": "image/jpeg",
  "id_doc_type": "PASSPORT",
  "country": "NGA",
  "file_name": "4a7f1c92e0_passport front.jpg"
}
'

{
  "message": "Verification session document uploaded successfully.",
  "data": {
    "id": "9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33",
    "business_id": "9d4c4ec5-572d-49de-a362-f01ed09f2b1b",
    "customer_reference": "user_10482",
    "requirements": [
      "DOCUMENTS"
    ],
    "fulfilment_mode": "HEADLESS",
    "status": "AWAITING_INPUT",
    "steps": {
      "documents": "SUBMITTED",
      "selfie": null,
      "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"
  }
}

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

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

{
  "message": "Verification session not found."
}

{
  "message": "No uploaded file was found under that name; upload to the presigned URL before confirming."
}

Verification sessions

Upload a verification document

Add one document to a session. Send the bytes one of two ways, never both: file_name names a file you already staged through the upload-url endpoint, and content_base64 carries the bytes inline. Use file_name for every real document, because a request body larger than about 8 KB is rejected at the network edge. An inline document must be 700 KB or smaller after decoding, and a staged file must be 5 MB or smaller. The session must be AWAITING_INPUT, and it must be HEADLESS. A HOSTED session refuses the call with a 422, because the end customer supplies the documents on the verification link. The response is the session, with steps.documents set to SUBMITTED. Merchant KYC must be enabled for your business. Required scope: compliance-kyc:create.

POST

api

external

compliance

kyc

sessions

{sessionId}

documents

curl --request POST \
  --url https://api-prod.blaaiz.com/api/external/compliance/kyc/sessions/{sessionId}/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "passport-front.jpg",
  "content_type": "image/jpeg",
  "id_doc_type": "PASSPORT",
  "country": "NGA",
  "file_name": "4a7f1c92e0_passport front.jpg"
}
'

{
  "message": "Verification session document uploaded successfully.",
  "data": {
    "id": "9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33",
    "business_id": "9d4c4ec5-572d-49de-a362-f01ed09f2b1b",
    "customer_reference": "user_10482",
    "requirements": [
      "DOCUMENTS"
    ],
    "fulfilment_mode": "HEADLESS",
    "status": "AWAITING_INPUT",
    "steps": {
      "documents": "SUBMITTED",
      "selfie": null,
      "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"
  }
}

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

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

{
  "message": "Verification session not found."
}

{
  "message": "No uploaded file was found under that name; upload to the presigned URL before confirming."
}

Authorizations

Authorization

string

header

required

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

Path Parameters

sessionId

string<uuid>

required

The verification session id returned by the create endpoint.

Body

application/json

filename

string

required

The name Blaaiz stores the document under.

Maximum string length: 191

content_type

enum<string>

required

The media type of the file.

Available options:

image/jpeg,

image/png,

image/webp,

application/pdf

id_doc_type

enum<string>

required

What the document is. UTILITY_BILL and BANK_STATEMENT satisfy the proof-of-address step. Every other type except SELFIE satisfies the documents step. Which types a session accepts depends on its requirement set. A session that includes SELFIE rejects a SELFIE upload, because Blaaiz captures the selfie.

Available options:

PASSPORT,

ID_CARD,

DRIVERS,

RESIDENCE_PERMIT,

UTILITY_BILL,

BANK_STATEMENT,

SELFIE

country

string

required

The country of the document, as an ISO 3166-1 alpha-3 code.

Required string length: 3

file_name

string

The data.file_name value the upload-url endpoint returned. Send this or content_base64, never both.

Maximum string length: 150

Pattern: ^[a-zA-Z0-9_ -]+\.(jpg|jpeg|png|webp|pdf)$

content_base64

string

The file, base64 encoded. The decoded file must be 700 KB or smaller. Send this or file_name, never both.

Response

Verification session document uploaded successfully.

message

string

required

data

object

required

Show child attributes