Read session data

After a session is APPROVED or REJECTED, you can read the data that the session captured:

• The applicant details that Blaaiz read from the documents: the name, the date of birth, the address, and the identity document.
• The images: the identity document, the selfie, the proof of address, and the face image from the liveness check.

Webhooks never carry this data. Read it from your server with the endpoints on this page.

Before you start

• Signa must be enabled for your business. Contact your account manager.
• Your OAuth credentials must carry the compliance-kyc:pii:read scope.

When the data is available

The data is available when the session status is APPROVED or REJECTED. For any other status, the endpoints return 409 with this message:

Session data is available once the session is APPROVED or REJECTED. This session is IN_REVIEW.

Wait for the merchant.kyc.session.completed webhook, then read the data.

Step 1: Get an access token

curl -X POST https://api-prod.blaaiz.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "scope=compliance-kyc:pii:read"

Step 2: Read the applicant details

curl -X GET https://api-prod.blaaiz.com/api/external/compliance/kyc/sessions/9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33/applicant-data \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "message": "Session applicant data retrieved successfully.",
  "data": {
    "session_id": "9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33",
    "first_name": "Amara",
    "middle_name": null,
    "last_name": "Okafor",
    "date_of_birth": "1993-04-17",
    "country": "NGA",
    "nationality": "NGA",
    "address": {
      "line": "14 Admiralty Way",
      "city": "Lagos",
      "state": "Lagos",
      "postal_code": "106104"
    },
    "document": {
      "type": "PASSPORT",
      "number": "A05729314",
      "issuing_country": "NGA",
      "issue_date": "2021-06-02",
      "expiry_date": "2031-06-01"
    },
    "extracted_at": "2026-08-29T09:31:07.000Z"
  }
}

• data is null when the session captured no applicant details.
• A field is null when the session did not capture it.
• document is null when the session has no identity document.
• country, nationality and document.issuing_country use ISO 3166-1 alpha-3 codes.

Step 3: List the images

curl -X GET https://api-prod.blaaiz.com/api/external/compliance/kyc/sessions/9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "message": "Session documents retrieved successfully.",
  "data": [
    {
      "id": "doc:901",
      "kind": "DOCUMENT",
      "document_type": "PASSPORT",
      "document_side": "FRONT_SIDE",
      "content_type": "image/jpeg",
      "available": true,
      "unavailable_reason": null
    },
    {
      "id": "doc:902",
      "kind": "SELFIE",
      "document_type": "SELFIE",
      "document_side": null,
      "content_type": "image/jpeg",
      "available": true,
      "unavailable_reason": null
    },
    {
      "id": "liveness:reference",
      "kind": "LIVENESS_REFERENCE",
      "document_type": null,
      "document_side": null,
      "content_type": "image/jpeg",
      "available": false,
      "unavailable_reason": "NOT_RETAINED"
    }
  ]
}

The list holds descriptions only. Treat each id as an opaque value: the format can change.

When available is false, unavailable_reason gives the cause:

Step 4: Download an image

Get a download URL for one image with its id:

curl -X GET https://api-prod.blaaiz.com/api/external/compliance/kyc/sessions/9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33/documents/doc:901 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "message": "Session document retrieved successfully.",
  "data": {
    "url": "https://storage.example.com/sessions/9f2c7b41/doc-901.jpg?expires=900&signature=EXAMPLE",
    "content_type": "image/jpeg",
    "expires_at": "2026-08-29T10:02:11.000Z"
  }
}

Send an HTTP GET to data.url with no Authorization header. Use the URL exactly as Blaaiz returns it. The URL stops working at expires_at, 15 minutes after the call.

Download the image at once. Do not store the URL, and do not send it to a browser or to another party.

Retention

Blaaiz keeps the face image from the liveness check for 30 days. After that:

• The list shows the image with available: false and unavailable_reason: NOT_RETAINED.
• A download URL call for the image returns 410 with the message This liveness reference image is no longer retained.

If you must keep an image, download it within 30 days and store it under your own retention rules.

Sessions completed with Signa ID

A person can complete a hosted session with Use Signa ID. See Signa ID on the verification page.

If the person or Blaaiz later stops your access to the Signa ID data, the session data endpoints return 404 for that session. Blaaiz sends no webhook for this change. The verdict and the webhook that you received stay valid, and the read endpoints still return the session. A download URL that Blaaiz issued before the change works until it expires.

Limits

The download URL endpoint allows 30 requests each minute and 600 requests each hour for each business. The Signa ID release document endpoint shares this limit. Above the limit, the call returns 429 with a Retry-After header.

Protect the data

• Every response carries Cache-Control: no-store. Do not cache the responses in a proxy or in a browser.
• Call the endpoints from your server only. Do not send the OAuth access token to a browser.
• Do not write applicant details, document numbers or download URLs to your logs.
• Store only the fields that you need, and delete them under your own retention rules.

Errors