Submit Customer KYC
POST/api/v2/client/:clientid/customer/kyc
Onboards an individual end customer by submitting their KYC details.
This endpoint serves two onboarding flows with different mandatory fields. Roma assigns your client to one flow during onboarding; it is not selectable per request. Confirm which flow applies to you with your Roma representative, then send the matching request variant — each one documents its own required fields, allowed values and per-flow notes.
| Flow | Request variant | Identity documents |
|---|---|---|
| Standard flow | SubmitKycStandardRequest | Sent inline, in documents[] and selfie |
| US flow | SubmitKycUsRequest | Sent separately, via Submit KYC Documents |
Country codes
ISO 3166-1 alpha-2 or alpha-3, upper-cased — a lower-case code is not corrected. The
US flow accepts 243 alpha-2 codes; AN, AQ, AX, BQ, BV, HM, TF and UM are
not among them.
Response
A 200 means the customer and KYC record were created and submitted for verification —
not that the customer is verified. Poll
Get Customer KYC Status or subscribe to the
KYC webhook; the customer can move money only at active.
status is initiated for a new customer. On the Standard flow, an email Roma already
knows returns status as an empty string alongside a kyc_link, so key off id and
customer_id rather than status. On the US flow a known email is rejected with 400
USER_ALREADY_EXISTS.
Request
Responses
- 200
- 400
- 401
- 403
- 500
The customer and KYC record were created and submitted for verification.
Validation failed. INVALID_PARAMETERS covers every US-flow rule and the Standard-flow name and nationality checks; the offending field is not named, so check the mandatory list above.
MISSING_TOKEN when the X-ROMA-Signature header is absent, INVALID_TOKEN when it matches no active credential.
Roma could not resolve the credentials for this clientid.
The submission could not be completed. No id is returned, and the email is already registered — resubmitting it returns 400 USER_ALREADY_EXISTS, so contact your Roma representative instead of retrying.