Signa overview
Verify the identity of your own customers with Blaaiz verification sessions.
Signa lets you run identity verification on your own customers through the Blaaiz Platform API. You create a verification session for one person, collect what the session asks for, and Blaaiz returns the result on a webhook.
The product is separate from Blaaiz customer KYC. A verification session does not create a Blaaiz customer, a wallet, or a virtual bank account. You link the session to your own records with the customer_reference field.
Signa must be enabled for your business before you can create a session. Contact your account manager or support@blaaiz.com to request access.
Access and scopes
Signa uses the same OAuth client credentials as the rest of the Platform API. See Authentication for the token request.
Three scopes control the endpoints:
| Scope | Endpoints |
|---|---|
compliance-kyc:read | List sessions, get one session |
compliance-kyc:create | Create a session, upload documents, get an upload URL, issue a verification link, submit a session |
compliance-kyc:cancel | Cancel a session |
The cancel action has its own scope because it is the one destructive action in the product. Request the scopes you need in the scope parameter of your token request.
The read and cancel endpoints stay available even when Signa is disabled for your business. You can always look up and cancel the sessions you already opened.
Fulfilment modes
Every session has a fulfilment_mode. The mode says who collects the input from the person you verify.
fulfilment_mode | Who collects the input | How you start it |
|---|---|---|
HOSTED | A verification page hosted by Blaaiz or by the Blaaiz verification partner. The page shows one step for each requirement in the set: the documents, the proof of address, and the selfie. | Send the person the verification_link that the create response returns. |
HEADLESS | Your own server. You upload the document images and the proof of address through the API. | Upload what the set asks for, then submit the session. |
Blaaiz decides which page a HOSTED session uses. Your integration does not change: send the person the verification_link, then wait for the webhook.
If you omit fulfilment_mode on create, Blaaiz selects a mode that the requirement set supports and your business is allowed to use.
Requirements
The requirements array says what the session must prove. The order does not matter, and Blaaiz stores one canonical order.
| Requirement | What it proves |
|---|---|
DOCUMENTS | The identity document is genuine. |
SELFIE | A live person is present at capture time. |
FACE_MATCH | The face on the selfie and the face on the document are the same person. |
PROOF_OF_ADDRESS | A recent utility bill or bank statement confirms where the person lives. |
FACE_MATCH is a separate requirement, not a side effect of SELFIE. A genuine document and a live person prove nothing on their own until a check confirms that they belong together. Because that check needs both faces, FACE_MATCH needs DOCUMENTS and SELFIE in the same set.
Supported combinations
Blaaiz supports the combinations in the table below. If you ask for any other combination, the create call fails with 422 and the message names the supported sets.
requirements | HOSTED | HEADLESS |
|---|---|---|
["DOCUMENTS"] | No | Yes |
["DOCUMENTS", "SELFIE", "FACE_MATCH"] | Yes | No |
["DOCUMENTS", "SELFIE", "FACE_MATCH", "PROOF_OF_ADDRESS"] | Yes | No |
["DOCUMENTS", "PROOF_OF_ADDRESS"] | Yes | Yes |
["PROOF_OF_ADDRESS"] | Yes | Yes |
Every set that includes PROOF_OF_ADDRESS is available in both modes, except the set that also includes SELFIE.
A documents-only set is never hosted, and a set with SELFIE is never
headless. The selfie proves that a live person is present, so Blaaiz must
capture it. A session that includes SELFIE rejects a SELFIE document
upload from your server.
Session lifecycle
status | Meaning | Terminal |
|---|---|---|
CREATED | Blaaiz created the session but it does not accept input yet. | No |
AWAITING_INPUT | The session accepts documents, a selfie, or both. | No |
IN_REVIEW | The session went to review. It accepts no more input. | No |
APPROVED | The checks passed. | Yes |
REJECTED | The checks failed. Read the rejection object. | Yes |
EXPIRED | The session passed its expires_at deadline before it completed. | Yes |
CANCELLED | You cancelled the session. | Yes |
A create call normally returns AWAITING_INPUT. CREATED means that Blaaiz did not finish the setup of the session. Repeat the create call with the same idempotency_key to finish it.
Terminal is final. After a session is terminal, Blaaiz sends no more webhooks for it and accepts no more input.
Steps
The steps object shows what is still outstanding while the session is AWAITING_INPUT.
| Field | Values | Notes |
|---|---|---|
steps.documents | PENDING, SUBMITTED, null | null when the requirement set has no DOCUMENTS. |
steps.selfie | PENDING, SUBMITTED, null | null when the requirement set has no SELFIE. |
steps.proof_of_address | PENDING, SUBMITTED, null | null when the requirement set has no PROOF_OF_ADDRESS. |
A null step is one the session never asks for. Ignore it.
Blaaiz sends a session for review only when every step that is not null is SUBMITTED. A submit call that leaves a step at PENDING fails with 422.
steps.documents is null on a ["PROOF_OF_ADDRESS"] session. Every other
supported set includes DOCUMENTS, so read the field rather than assume a
document step exists.
Rejections
When status is REJECTED, the rejection object holds the outcome. For every other status, rejection is null.
| Field | Description |
|---|---|
rejection.reason | Text you can show to the person. It can be null. |
rejection.type | FINAL or RETRYABLE. |
rejection.type | What to do |
|---|---|
RETRYABLE | The person can try again. Create a new session and collect fresh input. |
FINAL | Do not retry. The verification failed for good. |
A session is never reopened. Both rejection types need a new session for another attempt. The type tells you whether another attempt is worth it.
Idempotency
idempotency_key is required on create. Blaaiz stores it against your business, so your keys never collide with another merchant's keys.
- If you repeat a create call with a key you already used, Blaaiz returns the stored session. It does not create a second session.
- If you repeat the key with a different
customer_referenceor a different requirement set, the call fails with422. - Keys are never released. An expired or cancelled session keeps its key for good.
Use one key per person you verify, and store it with your own record of that person.
Session expiry
Every session carries an expires_at timestamp. Blaaiz expires a session that is still CREATED or AWAITING_INPUT at that deadline. A session that reached IN_REVIEW does not expire.
Read expires_at from the create response. Do not calculate the deadline yourself.
Open session limits
Blaaiz caps how many open sessions one business can hold. A session counts as open while its status is CREATED, AWAITING_INPUT, or IN_REVIEW.
When you reach the cap, a create call fails with 422 and this message:
Too many open verification sessions; complete, cancel, or let existing sessions expire.To stay under the cap, cancel the sessions you no longer need. If your volume needs a higher cap, contact support@blaaiz.com.
Next steps
Create a session, send the verification link, and get the result on your webhook.
Upload document images from your server and submit the session for review.
Register your kyc_url and verify the x-blaaiz-signature header.
All eight verification session endpoints.