> ## 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.

# Reusable KYC (Sumsub share token)

> Reuse a verification your customer already completed in your own Sumsub account, so they skip the document upload and liveness check.

If your customers are **already verified in your own Sumsub account**, you can share that verification with Ripio instead of putting the customer through the whole process again. You send a Sumsub **share token** when creating the KYC, Ripio redeems it, and — when both verifications are compatible — the customer skips the document upload and liveness check. That's not an automatic approval, though — the KYC still has to pass Ripio's own validation before it's `COMPLETED`.

<Info>
  This is an accelerator, not a third KYC model: it works on top of either [Ripio-hosted KYC (redirect)](/ramps-api/kyc/kyc-with-ripio) or [Partner-submitted KYC (API)](/ramps-api/kyc/kyc-via-api-overview). Everything else — statuses, webhooks, how you track the outcome — stays the same.
</Info>

## Prerequisites

Two things have to be in place before your first call, and neither of them is part of the API: Ripio has to enable the feature for your account, and your Sumsub account has to be paired with Ripio's as a sharing partner. Sort both out with the Ripio team before you start integrating.

<Warning>
  Reusable KYC is an **opt-in feature that must be enabled for your account by the Ripio team**. It is disabled by default. While it is disabled, any request that includes `kycProviderShareToken` returns `403 Forbidden` with the error code `20065` (`KycProviderTokenSharingNotEnabledException`) and **no KYC is created**. Contact the Ripio team to have reusable KYC enabled for your account before integrating it.
</Warning>

<Steps>
  <Step title="Add Ripio as a recipient in your Sumsub account">
    Ripio gives you a **partner token**. Add it in your Sumsub dashboard under **Reusable identity → Partners → Recipients → Add recipient**. That authorizes Ripio to receive the verifications you share: until it's done, any share token you generate is rejected when Ripio tries to redeem it.

    → Sumsub: [Add recipient](https://docs.sumsub.com/docs/manage-sharing-partners#add-recipient)
  </Step>

  <Step title="Align your verification level with Ripio's">
    Sumsub only transfers the verification steps that your level and Ripio's have **in common**. If they have none, no applicant is created and the reuse fails outright. Ask the Ripio team which level applies to the country you operate in — Sumsub's partner levels let Ripio share it with you in read-only mode, so you don't have to align the settings by hand. See [What Sumsub verifies, by country](/ramps-api/kyc/overview#what-sumsub-verifies-by-country) for the identity document and selfie requirements Ripio's level checks in each country.

    → Sumsub: [Reusable KYC share](https://docs.sumsub.com/docs/reusable-kyc-share) · [Share levels with partners](https://docs.sumsub.com/docs/manage-sharing-partners#share-levels-with-partners)
  </Step>

  <Step title="Generate a share token for each customer">
    For every customer, call Sumsub's `POST /resources/accessTokens/shareToken` with that customer's `applicantId` and `forClientId` set to **Ripio's Sumsub client ID** (the Ripio team provides it). The token you get back is what you send in `kycProviderShareToken`.

    → Sumsub: [Generate share token](https://docs.sumsub.com/reference/generate-share-token)
  </Step>
</Steps>

## How to use it

Add the root-level `kycProviderShareToken` field to the call that opens the verification:

* **Ripio-hosted (redirect)** — `POST /customers/{customerId}/kyc/`, alongside `redirectUrl`.
* **Partner-submitted (API)** — [Start KYC](/ramps-api/kyc/start-kyc). The token is redeemed at that point: if it resolves the customer's identity, `otpRequired` comes back `false` and no OTP is needed.

```bash theme={null}
curl --request POST \
  --url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "redirectUrl": "https://www.example.com/",
    "kycProviderShareToken": "_act-jwt-eyJhbGciOiJub25lIn0..."
  }'
```

The response is the same as any other KYC submission (`submissionId`, `providerUrl`, `createdAt`), and you track the outcome the same way: poll [Retrieve KYC Submission](/ramps-api/kyc/retrieve-kyc-submission) or subscribe to [KYC Events](/ramps-api/webhooks/kyc-events).

## Possible outcomes

Sending a share token does not change the shape of the flow — it changes how much the customer has to do. There are three outcomes:

| Outcome | What the customer sees | What you do |
| - | - | - |
| **Reused** | Nothing to upload: the document and liveness steps are already covered. | Nothing special. Track the submission as usual until it reaches `COMPLETED`. |
| **Partially reused** | Only the steps that couldn't be transferred, or that failed the re-check against Ripio's rules. | Nothing special — the customer completes the missing steps in the provider flow, as in a standard KYC. |
| **Not reused** | The full standard flow. | Nothing special. An invalid, expired or incompatible token does not fail the request: the KYC is created and runs as if no token had been sent. |

<Note>
  Sending a share token does not approve the KYC by itself, not even in the **Reused** case. It only decides how much the customer has to redo — the submission still has to pass Ripio's own validation, the same as any other KYC, and if something needs to be corrected or re-verified, the flow reopens for the customer to complete it. The one case that does approve immediately is the [OTP reuse flow](/ramps-api/kyc/kyc-via-api-overview): if the customer already has an approved KYC with Ripio, confirming the OTP approves them right away.
</Note>

## Things to keep in mind

* **Reuse is not guaranteed — it depends on Sumsub compatibility.** Sumsub only transfers the verification steps that overlap between your level and Ripio's, and it re-checks the shared documents against Ripio's rules (accepted document types, issuing country, expiry). If the levels have no matching steps the reuse is rejected; if a re-check fails, the customer is asked for the missing documents. Skipping the flow entirely is the best case, not a certainty — see Sumsub's [Reusable KYC share](https://docs.sumsub.com/docs/reusable-kyc-share) documentation.
* **The account opt-in controls trust.** A share token by itself does not enable this feature. Ripio must enable reusable KYC for your account; otherwise sending `kycProviderShareToken` returns `403` with `KycProviderTokenSharingNotEnabledException` and no KYC is created.
* **Share tokens are short-lived and single-use** (Sumsub's default lifetime is 20 minutes). Generate the token immediately before calling the endpoint, not ahead of time, and generate a fresh one for every attempt: a token that was already redeemed cannot be used again.
* **The token is only used when a new verification is opened.** If a verification is already in progress for that customer, the call is idempotent and the token is ignored.
* **One token per customer.** The share token must belong to the same person you are creating the KYC for.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.