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

# Sumsub token sharing

> Forward a verification you already ran in your own Sumsub account instead of re-verifying the user.

If you already run KYC in your own Sumsub account, you can forward that verification to Venly instead
of putting the user through a second flow. You pass a Sumsub **share token** when creating the account,
and Venly redeems it against your verification tenant.

## Three conditions, all required

This route is deliberately narrow. All of these must hold, or the request is rejected:

<CardGroup cols={3}>
  <Card title="Individuals only" icon="user">
    `partyType` must be `INDIVIDUAL`. KYC only — there is no KYB equivalent.
  </Card>

  <Card title="Self-custody only" icon="key">
    Your company's wallet type must be `SELF_CUSTODY`.
  </Card>

  <Card title="Tenant provisioned" icon="gear">
    Verification must be provisioned for your company.
  </Card>
</CardGroup>

| If this fails                             | You get                              |
| ----------------------------------------- | ------------------------------------ |
| `partyType` is not `INDIVIDUAL`           | `400 verification-kyc-only`          |
| Company wallet type is not `SELF_CUSTODY` | `400 verification-self-custody-only` |
| No provisioned verification tenant        | `400 verification-not-provisioned`   |

If any of these rule you out, use a [hosted verification link](/guides/finance/onboarding/hosted-verification)
instead — it has none of these constraints.

## Only at account creation

The token is accepted **only** on the inline party of
[`POST /accounts`](/api-reference/Finance-API/accounts/create-a-new-account):

```bash theme={null}
curl -X POST https://api.venlyfinance.com/v1/accounts \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-12345",
    "chain": "BASE",
    "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "party": {
      "partyType": "INDIVIDUAL",
      "firstName": "Jane",
      "lastName": "Doe",
      "sumsubToken": "_act-sbx-jwt-eyJhbGci..."
    }
  }'
```

Note the shape: it goes on the **inline `party` object**, not at the top level, and you must create the
party inline. There's no way to attach a token to a party you created earlier, and no way to attach one
to an existing account.

Sending it to [`POST /parties`](/api-reference/Finance-API/parties/create-a-new-party) instead is
rejected with `400 sumsub-token-not-supported`.

The field is **write-only**: never persisted, never returned in any response.

## The whole request rolls back on failure

The token is forwarded inside the **same transaction** that creates the party, account, and wallet. If
the forward fails, nothing is persisted — no party, no account, no wallet.

That's deliberate, and it makes your retry logic simple:

<Note>
  **On failure, get a fresh token and resubmit the entire request.** You never have to check what was
  partially created, reconcile a half-built account, or clean up an orphaned party.
</Note>

## Errors

| Status | Code                                | Retryable                   | Meaning                                           |
| ------ | ----------------------------------- | --------------------------- | ------------------------------------------------- |
| `400`  | `SUMSUB_TOKEN_NOT_REDEEMABLE`       | **Yes, with a fresh token** | The token is expired or already used.             |
| `400`  | `verification-kyc-only`             | No                          | `partyType` is not `INDIVIDUAL`.                  |
| `400`  | `verification-self-custody-only`    | No                          | Company wallet type is not `SELF_CUSTODY`.        |
| `400`  | `verification-not-provisioned`      | No                          | Verification not provisioned for your company.    |
| `500`  | `identity-verification-rejected`    | No                          | The platform rejected the token. Contact support. |
| `503`  | `identity-verification-unavailable` | **Yes**                     | Platform unreachable. Retry with a fresh token.   |

Every one of these rolls the transaction back, so a retry is always a clean, full resubmit.

## Mint the token late

<Warning>
  Share tokens are **single-use and short-lived**. Mint the token immediately before the
  account-creation call rather than caching it — a token minted earlier in a user session has likely
  expired by the time you use it, and that surfaces as `SUMSUB_TOKEN_NOT_REDEEMABLE`.
</Warning>

This is the most common failure with this route. If you're seeing it intermittently, look at how long
your token sits between minting and use, not at the Venly call.

Because retries need a *fresh* token, the resilient shape is: mint → submit → on failure, mint again →
submit again. Don't retry the same body.

## After it succeeds

The account is created and the verification is registered against your tenant. From there it behaves
exactly like the hosted route: the verdict is applied asynchronously to the party's `kycStatus`, and
you observe it via [Get a party](/api-reference/Finance-API/parties/get-party-details) or a
[webhook](/guides/finance/webhooks).

Forwarding a token is not itself a verdict. A successful `201` means the verification was accepted for
processing, not that the party is `VERIFIED`.

## Next steps

<CardGroup cols={2}>
  <Card title="Hosted verification links" icon="link" href="/guides/finance/onboarding/hosted-verification">
    The route with no eligibility constraints.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/finance/onboarding/troubleshooting">
    Tracking linkage and resolving failures.
  </Card>
</CardGroup>