Hosted verification quickstart

This quickstart uses the HOSTED fulfilment mode. Your customer opens a verification page, uploads the identity document, and does the selfie there. You write no capture code.

You can send the page as a link, or open it in a popup on your own website with the Signa web SDK.

Blaaiz hosts that page, or the Blaaiz verification partner hosts it. Blaaiz makes that choice for your business. Your integration is the same either way: send the person the verification_link from the create response.

The page also collects the proof of address when the session asks for it. The page shows one step for each requirement in the set, and nothing more.

Read Signa overview first for the session model.

Before you start

• Signa must be enabled for your business.
• Your OAuth credentials must carry the compliance-kyc:create and compliance-kyc:read scopes.
• Your kyc_url webhook must be registered. See Signa webhooks.

The examples use the production base URL https://api-prod.blaaiz.com. For development, use https://api-dev.blaaiz.com.

Flow

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:create compliance-kyc:read"

Step 2: Create the session

Ask for the full set: DOCUMENTS, SELFIE, and FACE_MATCH. Set fulfilment_mode to HOSTED. To collect the proof of address on the same page, add PROOF_OF_ADDRESS to requirements.

The applicant object is optional. Send the details you already hold so that the person types less on the verification page.

redirect_url is optional. The page sends the person to this URL after the last step. See Return the person to your site.

curl -X POST https://api-prod.blaaiz.com/api/external/compliance/kyc/sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    },
    "redirect_url": "https://yourapp.com/kyc/return"
  }'

The response returns the session:

{
  "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,
    "redirect_url": "https://yourapp.com/kyc/return",
    "expires_at": "2026-08-30T09:14:22.000Z",
    "completed_at": null,
    "created_at": "2026-08-29T09:14:22.000Z",
    "verification_link": "https://id.blaaiz.com/c/8Kq2rV5wZs1tYb7NfPjX0aLmC4hD6gEuR9oT3nQiWxs",
    "link_expires_at": "2026-08-29T09:44:22.000Z"
  }
}

Store data.id against your own record for user_10482. You need the session id for every later call.

Read data.verification_link and data.link_expires_at from this response. A HOSTED session carries both while it waits for the person. After the session moves to review or closes, both fields are null. Use the verification_link value exactly as it is returned. The host differs between environments, so do not build the URL yourself.

applicant.country uses the three-letter ISO 3166-1 alpha-3 code, such as NGA or CAN.

Step 3: Send the link to your customer

Send the verification_link to the person by email, SMS, or in your own app. The page asks the person for each step of the set in turn.

To open the page in a popup on your website instead, use the Signa web SDK.

Return the person to your site

Set redirect_url on create to send the person back to your site after the last step. These rules apply:

• The URL must use https and must be 2,048 characters or fewer. Otherwise the create call fails with 422 and the message The redirect URL must be a valid https URL.
• Only a page that Blaaiz hosts uses redirect_url. The page of the Blaaiz verification partner does not use it.
• redirect_url is part of the idempotency check. A repeat create with the same idempotency_key and a different redirect_url fails with 422.

After the last step, the page shows a done screen. Then the page goes to redirect_url after 5 seconds, or when the person selects Continue. Blaaiz adds the session_id query parameter, and keeps the other query parameters of your URL:

https://yourapp.com/kyc/return?session_id=9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33

Without redirect_url, the person stays on the done screen.

The redirect comes before the review result, so the URL carries no result. Read the result from the webhook, or from GET a session.

When the web SDK opens the page in a popup, the popup closes instead of the redirect.

Step 4: Wait for the webhook

When the review completes, Blaaiz posts merchant.kyc.session.completed to your kyc_url:

{
  "event": "merchant.kyc.session.completed",
  "data": {
    "session_id": "9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33",
    "business_id": "9d4c4ec5-572d-49de-a362-f01ed09f2b1b",
    "customer_reference": "user_10482",
    "requirements": ["DOCUMENTS", "SELFIE", "FACE_MATCH"],
    "result": "APPROVED",
    "rejection_reason": null,
    "rejection_type": null,
    "completed_at": "2026-08-29T09:31:05.000Z"
  }
}

Verify the x-blaaiz-signature header before you trust the payload. See Signa webhooks.

Issue a new verification link

The link stops working at link_expires_at. If the link expires before the person opens it, issue a new one. Use the same call when a link leaks.

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

{
  "message": "Verification link issued successfully.",
  "data": {
    "verification_link": "https://id.blaaiz.com/c/2Wd8sQ6pL4vXz0KbRm9TyH3uJ7cNfA1gE5oV2iBqZxs",
    "link_expires_at": "2026-08-29T10:12:40.000Z"
  }
}

Send the new link to the person. The previous link may stop working as soon as Blaaiz issues a new one, so treat the newest link as the only valid one.

A new link also stops the current web SDK access token of the session. If you use the web SDK, get a new access token after you issue a link.

This endpoint works for every HOSTED session, including a session with no selfie step. Blaaiz refuses the call when the session is terminal, and when the session is HEADLESS.

Signa ID on the verification page

A page that Blaaiz hosts can offer Signa ID to the person. Neither option changes your integration, and neither option shows on the page of the Blaaiz verification partner.

Save to Signa ID

On a session with a SELFIE step, the page shows a box that is not ticked: Save my verified identity to Signa ID so I can reuse it. When the person ticks the box, Blaaiz keeps the verified details in a Signa ID for the person.

• The option is on by default. To switch it off for your business, contact your account manager.
• Blaaiz does not tell you the choice of the person. The choice does not change the verdict, the webhook, or the session data.

Use Signa ID

On the first screen, the page offers Use Signa ID next to Verify now. A person who already has a Signa ID can share it, and does not upload the documents again.

• The option is off by default. To turn it on for your business, contact your account manager.
• The page offers it only for a session whose requirements include DOCUMENTS.
• The person signs in to Signa ID, sees the checks that you ask for, and takes one new selfie. Blaaiz checks that a live person is present and that the face matches the verified identity.
• The session completes as APPROVED. You get the same merchant.kyc.session.completed webhook, in the same shape.
• The applicant details that you sent on create must match the verified identity. If they do not match, the person cannot use Signa ID for the session.
• Blaaiz shares only what the requirements of the session cover. If the Signa ID cannot cover a requirement, the page asks the person to verify now.
• After 3 failed face matches, the page stops offering Use Signa ID for the session.

You read the data of the session with the session data endpoints, as for any other session. If the person or Blaaiz later stops your access to the Signa ID data, those endpoints return 404 for the session.

Check the status at any time

You do not have to wait for the webhook to read the state of a session:

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

Use the webhook as the trigger for your own work. Use the read endpoints to reconcile.

Cancel a session

If the person abandons the flow, cancel the session. A cancel frees a slot under your open-session cap and kills the verification link. This call needs the compliance-kyc:cancel scope.

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

A cancel on a session that is already terminal is refused with 422. A cancelled session answers This session has already been cancelled.; an approved, rejected or expired session answers This session has already reached a final state and cannot be cancelled. A cancel also closes the person's verification page: after it, the person cannot continue or upload.

This session is completed by the end customer on the verification link. Send the customer the verification_link, or call POST /sessions/{id}/verification-link to issue a new one.