curl --request POST \
--url https://skala-sandbox.ripio.com/api/v1/customers/{customerId}/kyc/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"kycSubmission": {
"country": "AR",
"first_name": "Mateo",
"last_name": "Romero",
"gender": "M",
"birthday": "1990-01-25",
"nationality": "AR",
"id_number": "11122233",
"id_number_type": "DNI",
"address": "Libertad",
"address_number": "333",
"address_flat": "4B",
"postal_code": "B1665DQJ",
"city": "San Miguel",
"state": "AR.BA",
"phone": "+542211228855",
"registered_tax_payer": false,
"cuit": "20388043629",
"net_income": "AR.A",
"personal_activity": "AR.1"
},
"redirectUrl": "https://www.example.com/"
}
'{
"submissionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"createdAt": "2023-11-07T05:31:56Z",
"providerUrl": "<string>",
"otpRequired": true
}Submit KYC Information
Submits KYC data for a specific customer. The response will include a URL to a third-party KYC provider’s widget for document uploads and liveness checks. Webhook events will notify about the validation process.
Production only: The provider URL for document uploads and liveness checks only works in production.
Reusable KYC (Sumsub share token). If the customer is already verified in your own Sumsub account, send their share token in kycProviderShareToken so Ripio redeems the existing verification instead of asking the customer to upload documents again. This is an opt-in feature that must be enabled for your account by the Ripio team; while it is disabled, sending the field returns 403 with the error code 20065 and no KYC is created. It also requires your Sumsub account to be paired with Ripio’s as a sharing partner — see Reusable KYC prerequisites before you integrate it.
This is separate from Ripio KYC reuse via OTP. If your account is configured for it, open the verification with Start KYC first and confirm the OTP with Validate KYC OTP — this endpoint cannot open that flow on its own, and calling it before the OTP is confirmed returns 400 with the error code 20094 (KycEmailOtpNotConfirmedException). Accounts should be configured for one reuse mechanism or the other, not both.
The payload is validated before anything is created. Formats, catalog values and cross-field rules are checked at the boundary, so a malformed field returns 400 with error code 20000 and no verification process is opened and no KYC is consumed — correct the field and repeat the same call. The fields accepted and required differ per country: see KYC fields by country.
curl --request POST \
--url https://skala-sandbox.ripio.com/api/v1/customers/{customerId}/kyc/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"kycSubmission": {
"country": "AR",
"first_name": "Mateo",
"last_name": "Romero",
"gender": "M",
"birthday": "1990-01-25",
"nationality": "AR",
"id_number": "11122233",
"id_number_type": "DNI",
"address": "Libertad",
"address_number": "333",
"address_flat": "4B",
"postal_code": "B1665DQJ",
"city": "San Miguel",
"state": "AR.BA",
"phone": "+542211228855",
"registered_tax_payer": false,
"cuit": "20388043629",
"net_income": "AR.A",
"personal_activity": "AR.1"
},
"redirectUrl": "https://www.example.com/"
}
'{
"submissionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"createdAt": "2023-11-07T05:31:56Z",
"providerUrl": "<string>",
"otpRequired": true
}kycProviderShareToken belongs to Reusable KYC (Sumsub share token). It is separate from Ripio KYC reuse via OTP, which uses Start KYC and Validate KYC OTP. If your account is configured for OTP reuse, this endpoint always requires kycSubmission — it cannot open that flow on its own. Calling it before the OTP is confirmed returns 400 with the error code 20094 (KycEmailOtpNotConfirmedException).For the Partner-submitted (API) model, send kycProviderShareToken in Start KYC instead — that’s the call that opens the verification, and where the token is redeemed. Sending it here has no effect for that model. This endpoint only accepts the token directly for the Ripio-hosted (redirect) model, where it has no separate Start KYC call. See Reusable KYC (Sumsub share token) for the full behavior per model.kycProviderShareToken returns 403 with KycProviderTokenSharingNotEnabledException and no KYC is created.Authorizations
Access token obtained via /oauth2/token/. Use as Authorization: Bearer <access_token>.
Path Parameters
Unique identifier for the customer.
Body
KYC data for the customer. Structure should align with fields from /kycRequirements/.
Request body for KYC submission. Use kycSubmission + redirectUrl for the standard API flow, or only redirectUrl for the Ripio KYC delegated flow. If your account is enabled for Reusable KYC (Sumsub share token), you can add kycProviderShareToken to reuse a verification the customer already completed in your own Sumsub account. This is separate from Ripio KYC reuse via OTP: if your account is configured for it, open the verification with Start KYC first and confirm the OTP with Validate KYC OTP — this endpoint cannot open that flow on its own, and calling it before the OTP is confirmed returns 400 with the error code 20094 (KycEmailOtpNotConfirmedException).
Customer KYC data. Which fields are accepted, and which are required, depends on country — the four countries have four different schemas, so the required list below is only their intersection. Each field's description states its per-country requiredness.
See KYC fields by country for the full matrix and the cross-field rules, and call /kycRequirements/ for the live catalogs of the CHOICE fields. Not required when using the Ripio KYC delegated flow.
Show child attributes
Show child attributes
URL to redirect the user after completing the KYC flow. Required for the Ripio KYC delegated flow; optional for the API flow.
"https://www.example.com/"
Optional. Sumsub share token for a customer already verified in your own Sumsub account (reusable KYC). Ripio redeems it so that, when both verifications are compatible, the customer does not have to upload documents or repeat the liveness check. On this endpoint, it only takes effect for the Ripio KYC delegated flow (no kycSubmission, only redirectUrl). For the API flow, send it on Start KYC instead — that is the call that opens the verification for that flow, and sending it here has no effect.
Two prerequisites must be met before this field does anything. First, reusable KYC is an opt-in feature that must be enabled for your account by the Ripio team: while it is disabled, sending this field returns 403 with the error code 20065 (KycProviderTokenSharingNotEnabledException) and no KYC is created. Second, your Sumsub account must be paired with Ripio's as a sharing partner — you add the partner token Ripio gives you under Reusable identity → Partners → Recipients → Add recipient in your Sumsub dashboard; without that pairing, the tokens you generate are rejected when Ripio tries to redeem them. See Reusable KYC prerequisites and Sumsub's Add recipient.
Generate the token with Sumsub's Generate share token endpoint, using the customer's applicantId and forClientId set to Ripio's Sumsub client ID.
Reuse is subject to Sumsub's compatibility rules: only the verification steps that overlap between your level and Ripio's are transferred, and the shared documents are re-checked against Ripio's requirements. When the levels have no matching steps, or a re-check fails, the customer is asked to complete the missing steps — see Sumsub's Reusable KYC share documentation.
Share tokens are short-lived and single-use: generate a fresh token right before each call to this endpoint. The token is only used when a new verification process is opened — if a verification is already in progress for the customer, the response is idempotent and the token is ignored.
2000Response
KYC submission received successfully. Includes providerUrl for document upload and liveness check.
Unique identifier for the submitted KYC data.
Date and time the KYC submission was created (UTC format).
Points to a third-party KYC provider's widget to handle file uploads and liveness checks. Only available in production.
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.
Was this page helpful?