> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ripio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Partner-submitted KYC (API)
> KYC flow where the partner collects the customer's data in their own UI and submits it through the Ramps API, with an OTP shortcut to reuse an existing Ripio KYC.
Not sure which KYC model to use? Start with [Overview & which model to use](/ramps-api/kyc/overview).
## How it works
In this model you collect the KYC fields in your own UI and submit them through the API. Collecting the data yourself does not skip the identity-provider step, though: the response from [Submit KYC Information](/ramps-api/kyc/submit-kyc-information) still includes a `providerUrl`, and you still redirect the customer to it. That page is Ripio's own UI, which resolves the document-upload and liveness check with the identity provider inside a webview — "API" describes who collects the personal data beforehand, not that you build your own document-capture screen.
Start with [Start KYC](/ramps-api/kyc/start-kyc) — this is the first call for every verification under this model. If your account is also configured for **Sumsub share-token reuse**, include `kycProviderShareToken` in that same call (see [Reusable KYC (Sumsub share token)](/ramps-api/kyc/reusable-kyc)).
If the customer is already verified in **your own Sumsub account**, you can share that verification with Ripio instead of running a new one: send a Sumsub share token in `kycProviderShareToken` and, if the two verifications are compatible, the customer skips the document upload and liveness check. This works with this API model as well as the [Ripio-hosted redirect model](/ramps-api/kyc/kyc-with-ripio). It is an opt-in feature that must be enabled for your account by the Ripio team — see [Reusable KYC (Sumsub share token)](/ramps-api/kyc/reusable-kyc).
### The flow
Call [Retrieve KYC Requirements](/ramps-api/kyc/retrieve-kyc-requirements) to get the fields required for your account's country, with the catalogs for every `CHOICE` field. [KYC fields by country](/ramps-api/kyc/kyc-fields-by-country) explains what each field means and what format it takes.
Call [Start KYC](/ramps-api/kyc/start-kyc) with `redirectUrl`. It takes no `kycSubmission`. If the customer has no email yet, set one with [Update Customer](/ramps-api/customers/update-customer) before calling it.
If [reusable KYC](/ramps-api/kyc/reusable-kyc) is enabled for your account, this is where `kycProviderShareToken` goes — the token is redeemed in this same call, not in a later one. Start KYC is a mandatory step for the reusable KYC flow under this model: there is no other call that accepts the token here.
The response's `otpRequired` tells you what to do next:
* **`true`** → continue with the next step.
* **`false`** → no OTP left to validate. Check the response's `status`: continue with [Submit KYC Information](/ramps-api/kyc/submit-kyc-information) if data is still missing, or move on to polling otherwise.
If the customer didn't get the email, or the code expired, call [Resend KYC OTP](/ramps-api/kyc/resend-kyc-otp).
Call [Validate KYC OTP](/ramps-api/kyc/validate-kyc-otp) with the code the customer received. In sandbox, `123456` always works — see [KYC in sandbox](/ramps-api/sandbox/kyc-in-sandbox).
* **The customer already has an approved KYC with Ripio** → this call approves them immediately. Nothing else to do.
* **They don't** → the OTP is confirmed, but the KYC is not approved yet. Continue with [Submit KYC Information](/ramps-api/kyc/submit-kyc-information) to send the customer's data.
Confirming the OTP only proves the customer owns that email — it does not by itself approve the KYC. Sending `kycSubmission` afterwards doesn't guarantee approval either: it always depends on what the identity provider reports back, and if something needs to be corrected or re-verified, the flow reopens for the customer to complete it.
Call [Submit KYC Information](/ramps-api/kyc/submit-kyc-information) with the customer's data. The response includes a `providerUrl` — redirect the user there to complete document upload and liveness check.
`kycProviderShareToken` does not go here. If [reusable KYC](/ramps-api/kyc/reusable-kyc) is enabled for your account, it was already redeemed in the [Start KYC](/ramps-api/kyc/start-kyc) call above — if it resolved the customer's identity, the document upload and liveness check are already covered by the time the customer reaches `providerUrl`.
The whole payload is validated before the verification is opened: formats, catalog values and cross-field rules. A bad value returns `400` with error code `20000`. Which fields are required, and what format each takes, **differs per country** — see [KYC fields by country](/ramps-api/kyc/kyc-fields-by-country).
The offending field is named in the response, nested under `kycSubmission`:
```json theme={null}
{
"code": 20000,
"type": "ValidationError",
"detail": {
"kycSubmission": {
"phone": [
{
"message": "Enter the phone in E.164 format, including the country code (e.g. +5491123456789).",
"code": "invalid_phone"
}
]
}
},
"status": 400
}
```
A `400` here means nothing was created: no verification is opened and the customer's KYC is not consumed. Correct the field and repeat the same call.
Call [Retrieve KYC Submission](/ramps-api/kyc/retrieve-kyc-submission) to poll the result. Once `status` is `COMPLETED`, the customer is verified and can operate.
***
## Webhooks
Instead of polling, you can configure a webhook URL to receive real-time notifications whenever a customer's KYC status changes. See [KYC Events](/ramps-api/webhooks/kyc-events) for the full payload reference.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.