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.