Skip to main content
POST
Start KYC
This endpoint is only for Ripio KYC reuse via OTP. It does not accept kycSubmission — identity data is sent afterwards through Submit KYC Information, once the OTP is confirmed (or skipped entirely, if the response already resolved the identity).
  • 400 KycAlreadyApprovedException (20015) — this customer already has an approved KYC on your account. No OTP is sent and nothing is opened; skip KYC entirely and continue with the quote.
  • 403 KycUnifiedFlowNotEnabledException (20095) — the unified KYC flow is not enabled for this account. This endpoint (and Resend KYC OTP / Validate KYC OTP) only works for accounts that run KYC through the API integration, authenticated with the API credentials. The most common cause is calling it with the widget credentials instead — the unified flow is only enabled for the API keys, not for the widget session credentials. Switch to the API credentials; if you already are, send the key ID (not the secret) to Ripio and we’ll check the account configuration.
  • otpRequired: true — validate the code with Validate KYC OTP before doing anything else. If the customer already has an approved KYC with Ripio, that validation approves them immediately — no data required.
  • otpRequired: false — no OTP left to validate. Check the response’s status: continue with Submit KYC Information if data is still missing, or move on to polling otherwise.

Authorizations

Authorization
string
header
required

Access token obtained via /oauth2/token/. Use as Authorization: Bearer <access_token>.

Path Parameters

customerId
string<uuid>
required

Unique identifier for the customer.

Body

application/json

Request body to start a KYC verification. Takes no identity data.

redirectUrl
string<uri>
required

URL to redirect the user to after completing the KYC flow.

Example:

"https://www.example.com/"

kycProviderShareToken
string

Optional. Sumsub share token for a customer already verified in your own Sumsub account (Reusable KYC) — see kycProviderShareToken on Submit KYC Information for the full behavior and prerequisites; it works the same way here.

Maximum string length: 2000

Response

KYC verification started.

submissionId
string<uuid>
required

Unique identifier for the submitted KYC data.

createdAt
string<date-time>
required

Date and time the KYC submission was created (UTC format).

providerUrl
string<url>
required

Points to a third-party KYC provider's widget to handle file uploads and liveness checks. Only available in production.

otpRequired
boolean

Whether the OTP sent to the customer's email still needs to be validated with Validate KYC OTP before continuing. Only present for accounts configured for Ripio KYC reuse via OTP.