Verify an individual customer with a Signa session that your business already completed. Use this when the person already passed Signa verification, so that they do not send their documents again.
Conditions. Blaaiz links the session only when all of these are true:
- The session belongs to your business and its status is
APPROVED. - The session requirements include
DOCUMENTS. - Blaaiz approved the session in the last 365 days.
- The verified document has not expired.
- No other customer is linked to the session, and no other customer of your business has the verified document number.
- The customer is an individual. Its status is
PENDING, orREJECTEDafter a provider review. A customer that compliance review rejected cannot be linked. - The session is not the one that the customer already used.
- The customer details agree with the verified person. Each name that you set must be in the verified name. If you set
dobin the KYC data, it must be the same as the verified date of birth. If you setid_type, it must agree with the type of the verified document.
What happens on success. The customer verification_status changes to VERIFIED at once, and a customer.status_changed webhook fires. Then Blaaiz copies the verified data to the customer: the name, the date of birth, the document number and dates, and the ID and selfie images. The verified data replaces the values that you sent. Blaaiz removes the images that you uploaded before the link.
Images. Blaaiz keeps session images for 30 days. If you link an older session, Blaaiz cannot copy the images. Some services, for example USD virtual accounts, need the ID image.
Required scopes: customer:write and compliance-kyc:pii:read. Signa must be enabled for your business.
Authorization
oauth2ClientCredentials customer:write, compliance-kyc:pii:readUse your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.
In: header
Scope: customer:write, compliance-kyc:pii:read
Path Parameters
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl --request POST \ --url 'https://example.com/api/external/customer/497f6eca-6276-4993-bfeb-53cbbbba6f08/kyc-session' \ --header 'Content-Type: application/json' \ --data '{ "signa_session_id": "0f8fad5b-d9cb-469f-a165-70867728950e"}'{ "message": "Customer verified with the Signa session successfully", "data": { "id": "019a6da3-4a9a-7033-81b9-12489eff13ee", "type": "individual", "first_name": "Ada", "last_name": "Obi", "verification_status": "VERIFIED" }}POSTSubmit customer for verification
Locks the customer for review and starts the verification flow. The customer's `verification_status` flips out of `PENDING` (or `REJECTED` on re-submission). **Readiness check.** This endpoint runs a set of checks before flipping the customer into `PROCESSING`. The same checks run on initial submission and on re-submission after a `REJECTED` verdict. If any check fails, the response is `422`, the customer stays editable, and you can fix the gap and call `/submit` again. **For business customers, what we check depends on `kyb_scope`.** Both scopes share the same identity baseline (business name, country, registration number, country of incorporation, formation document). The only difference: FULL also requires beneficial owners. *Individual customers* - `id_file` is uploaded (via the legacy `/files` flow). *Business customers — both MINIMAL and FULL* - `business_name` is set. - `country` (registered-address country) is set and a valid ISO 3166-1 alpha-2 code. - `registration_number` is set. - `incorporation_country` is set and a valid ISO 3166-1 alpha-2 code. - `country` equals `incorporation_country` — a company's registered office sits in its country of incorporation by company law. - At least one document of a formation type: `CERTIFICATE_OF_INCORPORATION`, `ARTICLES_OF_INCORPORATION`, `BENEFICIAL_OWNERSHIP_CERTIFICATE`, `INCORPORATION_DOCUMENTS`, or `CAC_STATUS_REPORT`. *Business customers (`kyb_scope=FULL`) — additional rules* - At least one owner is attached. - The sum of every owner's `ownership_percentage` equals exactly 100. - Owner emails are unique within the customer (case-insensitive). - For each owner: `id_document_front` is uploaded; `id_document_back` is uploaded for `drivers_license`, `id_card`, and `resident_permit` types and absent for `passport`. - For each owner that has the field set: `date_of_birth` is at least 18 years ago, `id_expiry_date` is strictly after today, and `nationality` / `country` / `id_document_country` are valid ISO alpha-2 codes. **Owners are NOT required for MINIMAL customers.** They're saved on the record if you upload them but they don't gate `/submit`. **What happens on success** depends on customer type and your business settings: - *Individual + external KYC enabled* → handed to the KYC provider for review. - *Individual + external KYC disabled* → marked `VERIFIED` immediately. - *Business + auto-verify enabled* → marked `VERIFIED` immediately. Every `PENDING` and `REJECTED` owner and document is also brought to `APPROVED` so the customer record is internally consistent. - *Business + auto-verify disabled* → moves to `PROCESSING` for manual compliance review. In the manual-review flow, every `PENDING` owner and every `PENDING` KYB document flips to `PROCESSING` along with the customer so they're visibly under review and frozen from further edits. Owners and documents that were already `APPROVED` or `REJECTED` from a prior cycle are not touched. A `customer.status_changed` webhook fires for the customer-level transition. There are no per-owner or per-document webhooks. **Verification is not instant.** For individual customers, review typically completes within minutes (up to 2 hours under additional screening). For business-type customers, review typically takes 1–5 business days. Do not escalate before the standard window — listen for the `customer.status_changed` webhook. Required scope: `customer:write`.
POSTUpgrade a business customer from MINIMAL to FULL KYB
Promote a `kyb_scope=MINIMAL` business customer to `kyb_scope=FULL` by attaching beneficial-owner data. Identity columns (`registration_number`, `incorporation_country`) are typically already on file from MINIMAL onboarding. **Eligibility checks (return `422` on failure):** - Customer exists and belongs to your platform. - Customer is `type=business`. - Customer is currently `kyb_scope=MINIMAL` (or has no scope set, treated as Minimal). A FULL customer cannot be "upgraded" again. - Customer is not `PROCESSING` (rejected with `400` — wait for the customer-level webhook before retrying). **Validation (return `422` on failure):** - At least one owner. - Ownership percentages sum to exactly 100. - Per-owner identity invariants (DOB ≥ 18, expiry future, valid ISO codes where supplied). - Owner emails unique within the customer. - If you send `registration_number` / `incorporation_country` overrides, they must satisfy the same rules as create. - If you send `country` to update jurisdiction, the resulting `country` and `incorporation_country` must match. **On success:** 1. New owners are saved on the customer. 2. `kyb_scope` flips to `FULL`. 3. If the customer was `VERIFIED`, `verification_status` flips back to `PENDING` (re-onboarding under stricter rules). Existing NGN VBAs are unaffected. 4. An audit comment is recorded. 5. A `customer.status_changed` webhook fires for the verification-status transition (if any). **Important:** This endpoint does NOT run the Standard readiness checks. Owner ID files are not part of this payload — upload them per-owner via `POST /api/external/customer/{id}/owner/{owner}/files` after the upgrade succeeds. Then call `POST /api/external/customer/{id}/submit` to re-verify the customer under the Standard checks. Required scope: `customer:write`.