> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Reuse KYC from Sumsub

> Let users you already verified with Sumsub skip re-verification: pair accounts once, then import each user with a one-time share token.

KYC reuse lets users you already verified with Sumsub become verified Agentcard users without redoing anything. You share the applicant with a one-time token, Agentcard imports the verification, and the user skips document capture and the face scan entirely. Without reuse, every user runs the full flow again on our side, and re-verification is where onboarding funnels go to die.

This page is for companies that run their own KYC on Sumsub. If you don't use Sumsub, or you'd rather not touch verification at all, the standard [identity verification flow](/companies/api/reference/kyc-status) already handles everything with a hosted page. For the verification status contract itself, see [Get verification status](/companies/api/reference/kyc-status).

<Note>
  KYC reuse is in early access. Ask your Agentcard contact to enable sharing for your organization: they'll send you the partner token and the Agentcard client id used below.
</Note>

## How it works

Sumsub calls this [Reusable KYC](https://docs.sumsub.com/docs/reusable-kyc): one Sumsub client (you, the donor) shares a verified applicant with another (Agentcard, the recipient). The share travels as a single-use token, so nothing about your Sumsub integration changes and no documents pass through your servers.

One rule explains the whole flow: **the import creates a real applicant in Agentcard's Sumsub account, copied from yours**. That's why the user skips re-verification (the documents and selfie arrive with the copy), why your applicant must come from a level with an identity document and a selfie check (the card program requires both, and an import that doesn't satisfy the receiving level is rejected), and why the result drops into the exact same [status contract](/companies/api/reference/kyc-status) as a fresh verification. After the import there is nothing special about these users.

## Pair the accounts (once)

Sumsub only allows sharing between linked partners, so an unpaired import fails no matter how valid the token is.

<Steps>
  <Step title="Get a partner token from Agentcard">
    Your Agentcard contact generates it in our Sumsub dashboard and sends it to you. Partner tokens are multi-use and expire 30 days after creation, so pair soon after receiving one.
  </Step>

  <Step title="Add Agentcard as a recipient">
    In your Sumsub dashboard, open **Reusable identity → Partners → Recipients**, click **Add recipient**, and paste the token. Agentcard appears in your recipients list once you confirm.
  </Step>
</Steps>

Pairing is per environment: production tokens carry an `Iv` prefix and sandbox tokens an `sbx` prefix, and a token only works in the environment that created it. Pair both if you plan to test in sandbox first.

## Share a user

Two calls per user: generate a share token on your side, then hand it to Agentcard.

### 1. Generate a share token

Call Sumsub with the applicant you want to share. `forClientId` is the Agentcard client id from your pairing email, and the call needs a Sumsub app token whose role includes the **Share applicants data** permission:

```bash cURL theme={null}
curl -X POST 'https://api.sumsub.com/resources/accessTokens/shareToken' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Token: $SUMSUB_APP_TOKEN' \
  -H 'X-App-Access-Sig: <signature>' \
  -H 'X-App-Access-Ts: <unix-timestamp>' \
  -d '{
        "applicantId": "63e092c51b7b4030f2e01154",
        "forClientId": "AGENTCARD_CLIENT_ID",
        "ttlInSecs": 600
      }'
```

Sumsub returns the token:

```json Output theme={null}
{
  "token": "_act-jwt-eyJhbGciOiJub25lIn0...",
  "forClientId": "AGENTCARD_CLIENT_ID"
}
```

Share tokens are single-use and expire after `ttlInSecs`, so generate one fresh per import attempt rather than storing them. A stored token that was already spent, or that outlived its TTL, fails the import with an invalid-token error.

### 2. Import it into Agentcard

Send the token to Agentcard for a [connected user](/connect/users), authenticated with your org bearer like every other `/api/v2` call:

```bash cURL theme={null}
curl -X POST https://api.agentcard.sh/api/v2/kyc/import \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "USER_ID", "share_token": "_act-jwt-eyJhbGciOiJub25lIn0..."}'
```

The response is the standard verification status object. For a complete applicant it lands on `pending` while our checks run, then `approved`:

```json Output theme={null}
{
  "object": "kyc",
  "status": "pending"
}
```

From here the normal loop takes over, which means you already have everything built for it: poll [GET /api/v2/kyc](/companies/api/reference/kyc-status) or listen for the [`identity.verification.updated`](/ship/webhooks) webhook, exactly as you would for a fresh verification.

## What still gets asked

The identity work transfers: documents, the selfie, and the extracted identity data. Two things can still come back to the user:

* **Program fields.** The card program requires a few typed details (occupation and annual income, for example) that your Sumsub level may not collect. When they're missing, the status lands on `needs_information` with the exact `required_fields`: submit them via [POST /api/v2/kyc/information](/companies/api/reference/kyc-submit-information), or hand the user the `iframe_url`, which collects them on the hosted page in under a minute.
* **Screening.** Agentcard runs its own compliance screening on every imported applicant, so an import can still end `rejected`. Reuse skips the user's effort, not the checks.

## When the import fails

| Failure                     | Cause                                                               | Fix                                                                                     |
| --------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Invalid or expired token    | Share tokens are single-use with a short TTL                        | Generate a fresh token right before each import call                                    |
| Sharing not allowed         | The accounts aren't paired, or were paired in the other environment | Complete [pairing](#pair-the-accounts-once) in the matching environment                 |
| Verification not compatible | The applicant's level lacks an identity document or selfie check    | Share applicants from a level that includes both, or let the user run the standard flow |

## Test in sandbox

Pair in the Sumsub sandbox (the `sbx`-prefixed partner token) and run the same two calls with sandbox credentials on both sides. If you want to exercise your status-handling code without a Sumsub sandbox at all, [POST /api/v2/kyc/simulate](/companies/api/reference/kyc-simulate) drives a sandbox user to any terminal status directly.

Once a sandbox import reaches `approved`, you've seen the whole loop: the same sequence is what production runs.

## Next steps

* [Connect users](/connect/users): the connection every import hangs off
* [Get verification status](/companies/api/reference/kyc-status): the status contract imports resolve into
* [Webhooks](/ship/webhooks): get `identity.verification.updated` pushed instead of polling