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 with400— 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_countryoverrides, they must satisfy the same rules as create. - If you send
countryto update jurisdiction, the resultingcountryandincorporation_countrymust match.
On success:
- New owners are saved on the customer.
kyb_scopeflips toFULL.- If the customer was
VERIFIED,verification_statusflips back toPENDING(re-onboarding under stricter rules). Existing NGN VBAs are unaffected. - An audit comment is recorded.
- A
customer.status_changedwebhook 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.
Authorization
oauth2ClientCredentials customer:writeUse your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.
In: header
Scope: customer:write
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
application/json
curl --request POST \ --url 'https://example.com/api/external/customer/497f6eca-6276-4993-bfeb-53cbbbba6f08/upgrade-kyb-scope' \ --header 'Content-Type: application/json' \ --data '{ "trading_name": "Acme", "business_type": "llc", "incorporation_date": "2019-03-12", "industry_type": "Software & SaaS", "business_description": "B2B SaaS platform.", "website": "https://acme.example.com", "source_of_funds": "business_revenue", "estimated_annual_revenue": "1000000_4999999", "expected_monthly_payments": 250, "account_purpose": "send_receive_funds_related_parties", "owners": [ { "first_name": "Jane", "last_name": "Doe", "email": "jane@acme.example.com", "date_of_birth": "1985-04-22", "nationality": "NG", "title": "CEO", "ownership_percentage": 60, "has_control": true, "is_signer": true, "is_beneficial_owner": true, "id_document_type": "passport", "id_document_number": "A12345678", "id_document_country": "NG", "id_expiry_date": "2030-01-15", "is_pep": false }, { "first_name": "John", "last_name": "Smith", "ownership_percentage": 40, "is_beneficial_owner": true } ]}'{ "message": "Customer KYB scope upgraded to FULL. Upload owner ID files and call /submit to re-verify.", "data": { "id": "019a6da3-4a9a-7033-81b9-12489eff13ee", "type": "business", "kyb_scope": "FULL", "verification_status": "PENDING", "business_name": "Acme Nigeria Limited", "registration_number": "RC123456", "incorporation_country": "NG", "country": "NG", "owners": [ { "id": "019a6e22-8b4c-7c8d-9d12-c0c1ab3f1a90", "first_name": "Jane", "last_name": "Doe", "ownership_percentage": 60, "status": "PENDING" }, { "id": "019a6e22-8b4c-7c8d-9d12-d1d2bc4e2b91", "first_name": "John", "last_name": "Smith", "ownership_percentage": 40, "status": "PENDING" } ] }}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.
GETList customer KYB documents
Returns every KYB document the business has registered for this customer. Each row's `url` is a 2-minute presigned link to the underlying file. The customer must be of type `business`. Required scope: `customer:read`.