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

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

    Partner tokens expire **30 days** after Sumsub generates them, so add it as soon as you get it — if it lapses, ask the Ripio team for a new one.

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

    → 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 [Submit KYC Information](/ramps-api/kyc/submit-kyc-information). It works with **both** models — on its own for the Ripio-hosted redirect flow, or alongside a full `kycSubmission` body for the partner-submitted API flow.

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

## 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.
* **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.
* **Reuse is verified in production.** The partner setup with Ripio is done on production accounts, so that is where the reuse actually runs. You can add the field to your integration beforehand — it is accepted and stored — but the end-to-end behaviour, the customer actually skipping the document upload and liveness check, is only observable in production.
* **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.
* **API integration only.** This field is not part of the [Widget integration](/ramps-api/widget/introduction), and it does not apply to the [OTP shortcut](/ramps-api/kyc/kyc-via-api-overview#kyc-reuse-via-otp), which reuses a KYC the customer already has *with Ripio* rather than with you.