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. 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.
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
Customer ID
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl --request POST \ --url 'https://example.com/api/external/customer/string/files' \ --header 'Content-Type: application/json' \ --data '{ "id_file": "file_123456", "id_file_back": "file_234567", "proof_of_address_file": "file_789012", "liveness_check_file": "file_345678"}'{ "message": "Customer files uploaded successfully"}POSTAdd KYC details
Add KYC details for a customer. Verification stays PENDING until documents are uploaded and reviewed. The customer's country must match the country on the identity document submitted for KYC. Accepted identity documents: Driver's License, Passport, or Resident Permit for individual customers, Certificate of Incorporation for business customers. ID cards (National Identity Cards) are not 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. Required scope: `customer:write`.
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`.