KYC via Sumsub share token

If your platform already uses Sumsub for identity verification, you can pass a share token to Contro instead of re-collecting KYC data. This avoids duplicate verification and provides a faster onboarding experience.

Prerequisites

Your platform is a Sumsub client (the “donor”)
Your user has completed KYC verification on your Sumsub-integrated platform
You can generate share tokens from your Sumsub account targeting Contro’s client ID

Flow

Your user completes KYC on your platform via Sumsub
You generate a Sumsub share token targeting Contro’s client ID
Call POST /partner/cardholders with kycSource: "sumsub" and the share token
Contro imports the applicant data immediately — the token is not stored

Create a cardholder with Sumsub KYC

curl -X POST https://api.contro.me/v1/partner/cardholders \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_42",
    "kycSource": "sumsub",
    "sumsubShareToken": "eyJhbGciOiJub25lIn0...",
    "email": "jane@example.com",
    "phoneNumber": "+14155552671"
  }'

const cardholder = await contro.cardholders.create({
  externalUserId: "user_42",
  kycSource: "sumsub",
  sumsubShareToken: "eyJhbGciOiJub25lIn0...",
  email: "jane@example.com",
  phoneNumber: "+14155552671",
});

cardholder = contro.cardholders.create(
    external_user_id="user_42",
    kyc_source="sumsub",
    sumsub_share_token="eyJhbGciOiJub25lIn0...",
    email="jane@example.com",
    phone_number="+14155552671",
)

const cardholder = await fetch(`${BASE_URL}/partner/cardholders`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    externalUserId: "user_42",
    kycSource: "sumsub",
    sumsubShareToken: "eyJhbGciOiJub25lIn0...",
    email: "jane@example.com",
    phoneNumber: "+14155552671",
  }),
}).then((r) => r.json());

Key details

firstName and lastName are extracted automatically from the imported Sumsub applicant data. You do not need to provide them.
The share token is imported immediately at cardholder creation time. It is not stored.
If the imported applicant is already approved, kycStatus is set to "approved" right away.
If the applicant is still pending review in Sumsub, kycStatus starts as "pending" and updates via webhook when Sumsub completes the review.

Required fields

Field	Type	Description
`externalUserId`	string	Your unique identifier for this user
`kycSource`	string	Must be `"sumsub"`
`sumsubShareToken`	string	Sumsub share token from your platform
`email`	string	Valid email address
`phoneNumber`	string	E.164 formatted phone number

Sandbox behavior

In sandbox mode, the share token import is skipped. A dummy applicant ID is stored and KYC is auto-approved.

Getting started

Core resources

Platform

KYC via Sumsub share token

Prerequisites

Flow

Create a cardholder with Sumsub KYC

Key details

Required fields

Sandbox behavior

​Prerequisites

​Flow

​Create a cardholder with Sumsub KYC

​Key details

​Required fields

​Sandbox behavior

Prerequisites

Flow

Create a cardholder with Sumsub KYC

Key details

Required fields

Sandbox behavior