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_type": "DNI",
    "id_number": "11122233",
    "registered_tax_payer": false,
    "cuit": "20111222330",
    "address": "Libertad",
    "address_flat": "1",
    "address_number": "333",
    "postal_code": "1012",
    "district": "Chubut",
    "city": "Trelew",
    "state": "AR.CH",
    "phone": "+542211228855",
    "personal_activity": "AR.6"
  },
  "redirectUrl": "https://www.example.com/"
}
'

{
  "submissionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "providerUrl": "<string>"
}

{
  "submissionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "providerUrl": "<string>"
}

{
  "code": 123,
  "type": "<string>",
  "detail": {
    "message": "<string>"
  },
  "status": 123
}

{
  "code": 40001,
  "type": "NotAuthenticated",
  "detail": {
    "message": "Authentication credentials were not provided.",
    "code": "not_authenticated"
  },
  "status": 401
}

{
  "code": 20065,
  "type": "KycProviderTokenSharingNotEnabledException",
  "detail": {
    "message": "KYC provider token sharing is not enabled for this account."
  },
  "status": 403
}

{
  "code": 40004,
  "type": "NotFound",
  "detail": {
    "message": "Not found.",
    "code": "not_found"
  },
  "status": 404
}

KYC

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.

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.

POST

api

customers

{customerId}

kyc

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_type": "DNI",
    "id_number": "11122233",
    "registered_tax_payer": false,
    "cuit": "20111222330",
    "address": "Libertad",
    "address_flat": "1",
    "address_number": "333",
    "postal_code": "1012",
    "district": "Chubut",
    "city": "Trelew",
    "state": "AR.CH",
    "phone": "+542211228855",
    "personal_activity": "AR.6"
  },
  "redirectUrl": "https://www.example.com/"
}
'

{
  "submissionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "providerUrl": "<string>"
}

{
  "submissionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "providerUrl": "<string>"
}

{
  "code": 123,
  "type": "<string>",
  "detail": {
    "message": "<string>"
  },
  "status": 123
}

{
  "code": 40001,
  "type": "NotAuthenticated",
  "detail": {
    "message": "Authentication credentials were not provided.",
    "code": "not_authenticated"
  },
  "status": 401
}

{
  "code": 20065,
  "type": "KycProviderTokenSharingNotEnabledException",
  "detail": {
    "message": "KYC provider token sharing is not enabled for this account."
  },
  "status": 403
}

{
  "code": 40004,
  "type": "NotFound",
  "detail": {
    "message": "Not found.",
    "code": "not_found"
  },
  "status": 404
}

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

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. In both cases you can add kycProviderShareToken to reuse a verification the customer already completed in your own Sumsub account (opt-in feature).

kycSubmission

object

Customer KYC data. Fields vary by country — use /kycRequirements/ to get the required fields for the customer's country. Not required when using the Ripio KYC delegated flow.

Show child attributes

redirectUrl

string<uri>

URL to redirect the user after completing the KYC flow. Required for the Ripio KYC delegated flow; optional for the API flow.

Example:

"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. Works with both the API flow and the Ripio KYC delegated flow.

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 (partner tokens expire 30 days after Sumsub generates them); 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.

Maximum string length: 2000

Response

KYC submission received successfully. Includes providerUrl for document upload and liveness check.

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.

⌘I

Overview

Widget integration

API Integration

Submit KYC Information

Authorizations

Path Parameters

Body

Response