Signa overview

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.

Access and scopes

Signa uses the same OAuth client credentials as the rest of the Platform API. See Authentication for the token request.

Four scopes control the endpoints:

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.

compliance-kyc:pii:read gives access to personal data, so it is separate from compliance-kyc:read. No scope bundle contains it, full-access included. Select it by name when you create or rotate your credentials. See Read session data.

The list, get and cancel endpoints stay available when Signa is disabled for your business. You can always look up and cancel the sessions you already opened. All other endpoints, the session data endpoints included, need Signa to be enabled.

Fulfilment modes

Every session has a fulfilment_mode. The mode says who collects the input from the person you verify.

Blaaiz decides which page a HOSTED session uses. Your integration does not change: send the person the verification_link, then wait for the webhook. The web SDK can open only a page that Blaaiz hosts.

A page that Blaaiz hosts can also offer Signa ID to the person. See Signa ID on the verification page.

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. It holds 1 to 5 values, and each value can appear one time. A repeated value fails with 422. The order does not matter, and Blaaiz stores one canonical order.

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.

AML_SCREENING has no step. The person and your server upload nothing for it. See AML screening.

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.

Every set that includes PROOF_OF_ADDRESS is available in both modes, except the set that also includes SELFIE.

You can add AML_SCREENING to each of the other sets in the table. The set then keeps the modes that it has without AML_SCREENING. For example, ["DOCUMENTS", "SELFIE", "FACE_MATCH", "AML_SCREENING"] is HOSTED only, and ["DOCUMENTS", "AML_SCREENING"] is HEADLESS only.

AML_SCREENING alone is HEADLESS only, because the person has nothing to capture. A HOSTED create for ["AML_SCREENING"] fails with 422.

Session lifecycle

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.

A ["AML_SCREENING"] session has nothing to collect, so the create call returns IN_REVIEW.

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.

A null step is one the session never asks for. Ignore it. AML_SCREENING has no step, so all three steps are null on a ["AML_SCREENING"] session.

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.

Rejections

When status is REJECTED, the rejection object holds the outcome. For every other status, rejection is null.

When the AML screening finds a match, Blaaiz rejects the session with rejection.type set to FINAL. rejection.reason is then This verification could not be completed. The reason never names the lists. The kinds of list are in aml_screening.match_types. See AML screening.

AML screening

AML_SCREENING checks the person against sanctions lists, lists of politically exposed persons (PEP), adverse media, and criminal lists. It is one check. You cannot ask for one kind of list alone.

When the screening runs

While the screening runs, the session stays IN_REVIEW. Blaaiz sends merchant.kyc.session.completed only after the screening gives its result:

• If the screening finds no match, the session is APPROVED.
• If the screening finds a match, the session is REJECTED, with rejection.type set to FINAL.
• If the screening gives no result in the 72 hours after it starts, the session is EXPIRED. Blaaiz sends merchant.kyc.session.expired.
• If the screening cannot use the details, for example because the date of birth is not valid, the session is REJECTED, with rejection.type set to FINAL. aml_screening.status is NOT_PERFORMED, because no screening took place. Create a new session with correct details.

If the review rejects the other requirements, Blaaiz does not screen the person. The session is REJECTED with the reason of that review, and aml_screening.status is NOT_PERFORMED. Blaaiz sends the webhook at once.

Applicant details for a set without DOCUMENTS

A set without DOCUMENTS has no identity document that names the person. Blaaiz screens the applicant details that you send, so the create call must include all four fields:

• applicant.first_name
• applicant.last_name
• applicant.dob, in YYYY-MM-DD format
• applicant.country, as an ISO 3166-1 alpha-3 code

If a field is missing or empty, or the country code is not valid, the create call fails with 422 and this message:

AML_SCREENING without DOCUMENTS needs applicant.first_name, applicant.last_name, applicant.dob and applicant.country.

Blaaiz does not compare these details with a document. Send the legal name and the date of birth of the person.

On a set with DOCUMENTS, the applicant fields stay optional, and Blaaiz does not screen them.

Screening only

A ["AML_SCREENING"] session has nothing to collect:

1. Create the session with the four applicant fields.
2. Wait for the merchant.kyc.session.completed webhook, or poll GET a session.

The create call returns IN_REVIEW, and the screening starts at once. Do not upload documents, and do not submit the session. Blaaiz refuses both. See AML screening only.

Read the result

Every session response has the aml_screening field. The merchant.kyc.session.completed webhook has it too. The field is null when requirements has no AML_SCREENING.

"aml_screening": {
  "status": "MATCH",
  "match_types": ["SANCTIONS", "PEP"]
}

A MATCH always has one type or more. aml_screening has no screening date.

Signa ID

A person can use Signa ID on a hosted session whose set includes DOCUMENTS. When the set also includes AML_SCREENING, the Signa ID covers the screening only if its last screening is CLEAR and 90 days old or less.

• If the Signa ID covers the screening, aml_screening.status is CLEAR. Blaaiz does not screen the person again for the session, so the CLEAR can come from a screening up to 90 days old.
• If the last screening is older than 90 days, or the Signa ID has no screening, the person cannot use Signa ID for the session. The page asks the person to verify now, and Blaaiz screens the person after the review.

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 and the same details, Blaaiz returns the stored session. It does not create a second session.
• If you repeat the key with a different detail, the call fails with 422. Blaaiz compares customer_reference, requirements, fulfilment_mode, the applicant fields, and redirect_url.
• Verification sessions and Signa ID release requests share one set of keys. A key that a release request uses fails with 422 on a session create.
• 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 at expires_at.

Read expires_at from the create response. Do not calculate the deadline yourself.

One exception applies. A session that waits for its AML screening expires when the screening gives no result in the 72 hours after it starts. expires_at does not show this deadline, and Blaaiz sends merchant.kyc.session.expired when it passes.

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