SupportDashboard
HomeGet StartedPaymentsCryptoComplianceChangelog

Submit 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.

POSTapi-prod.blaaiz.com/api/external/customer/{customer}/submit

Authorization

oauth2ClientCredentials customer:write
AuthorizationBearer <token>

Use your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.

In: header

Scope: customer:write

Path Parameters

customer*string
Formatuuid

Response Body

application/json

application/json

application/json

Submit customer for verification
curl --request POST \  --url 'https://example.com/api/external/customer/497f6eca-6276-4993-bfeb-53cbbbba6f08/submit'
{  "message": "Customer submitted for verification successfully",  "data": {    "id": "019a6da3-4a9a-7033-81b9-12489eff13ee",    "type": "business",    "verification_status": "PROCESSING",    "owners": [      {        "id": "019a6e22-8b4c-7c8d-9d12-c0c1ab3f1a90",        "first_name": "Jane",        "status": "PROCESSING"      }    ],    "documents": [      {        "id": "019a6e10-1fb3-7b2f-8f8b-ad1e92c4017a",        "type": "CERTIFICATE_OF_INCORPORATION",        "status": "PROCESSING"      }    ]  }}

POSTUpload files for a customer

**Individual customers only.** Upload verification files for an individual customer. Use `file_id` values from the File API presigned upload. Newly uploaded files override previous records. The `id_file` must be uploaded for verification. **Do not call this endpoint for `type=business` customers.** Business-type customers use the KYB flow — see [Business customer KYB](/docs/guides/kyb/overview). The legacy `id_file_path` is not consulted by `/submit` for business customers, so calling this endpoint achieves nothing for them. The identity document must be a Driver's License, Passport, or Resident Permit. ID cards (National Identity Cards) are not accepted. No other document types are accepted. All uploaded documents must be clear, legible, and authentic — unclear images will be rejected. Fraudulent or falsified documents will result in the customer being permanently blacklisted from the platform. IMPORTANT: Verification is not instant. After documents are uploaded, they go through a review process. This typically takes a few minutes, but can take up to 2 hours if the documents require additional screening. Do not escalate before 2 hours — such enquiries will not be attended to. If verification has been pending for 5 hours or more, contact the operations team to expedite. Listen for the `customer.verified` or `customer.rejected` webhook to know when the review is complete. Required scope: `customer:write`.

POSTVerify customer with a Signa session

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`, or `REJECTED` after 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 `dob` in the KYC data, it must be the same as the verified date of birth. If you set `id_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.