Identity Verification (KYC)

Overview

Identity verification is how a user earns a Sigil — their portable, verified Proof of Personhood. This guide covers the full KYC (Know Your Customer) flow that backs it. Three verification modes are available, controlled per integration via a server-side configuration:

WebSDK mode (default) — the embedded third-party SDK handles everything: document upload, selfie capture, and liveness checks
Hybrid mode — your app uploads documents via the API, then launches the SDK for a liveness-only step
Document-only mode — your app uploads documents via the API with no SDK or liveness step required

The active mode is communicated to your frontend via meta.kyc_mode on the kyc_verification onboarding step. The value is "websdk", "hybrid", or "document_only". The KYC system is:

Webhook-updated — verification results arrive asynchronously; your client polls for the final outcome
GDPR-compliant — only the user’s name is stored locally; all identity documents and PII are held by the verification provider
Onboarding-integrated — when KYC is approved while the user is on the kyc_verification onboarding step, onboarding auto-advances to the next step

Sumvin holds the outcome, not the documents. The envelope around the verification is ours; the payload stays with the provider.

Quick Start

WebSDK Mode

No additional CORS configuration is required. The WebSDK runs in a SumSub-hosted iframe — your origin only needs CORS allowed on the Sumvin API itself (handled by the standard API config), not on id.sumsub.com or api.sumsub.com. The SIS dashboard CORS origin allowlist governs blockchain RPC traffic, not KYC.

1. Create the applicant (idempotent)

Before requesting an access token, create the SumSub applicant for the user. This is idempotent — safe to call on every entry into the verification flow.

curl -X POST /v0/kyc/applicant \
  -H "x-juno-jwt: <token>"

{
  "applicant_id": "65abc123def456",
  "user_id": "usr_abc123",
  "already_existed": false,
  "_links": { ... }
}

If the user already has an applicant, the response includes "already_existed": true. Either way, proceed to step 2.

You can skip this step and call /v0/kyc/access-token directly — the WebSDK will create the applicant on first interaction. Calling /v0/kyc/applicant first is preferred because it pins the sumsub_applicant_id server-side immediately, which makes status polling and webhook correlation more reliable.

2. Generate an SDK access token

curl -X POST /v0/kyc/access-token \
  -H "x-juno-jwt: <token>"

{
  "access_token": "_act-sbx-...",
  "expires_in": 600,
  "user_id": "usr_abc123",
  "_links": {
    "self": { "href": "/v0/kyc/access-token", "method": "POST" },
    "status": { "href": "/v0/kyc/status" }
  }
}

The token is valid for 600 seconds (10 minutes). Generate a new one if it expires before the user finishes — see the expirationHandler below.

3. Embed the SumSub SDK

Pick the SumSub SDK that matches your platform. Both consume the same access_token from step 2.

Web (React)
React Native

The WebSDK runs in a SumSub-hosted iframe; your origin does not need to be allowlisted with SumSub for the iframe to load. The reference integration in our B2C app uses @sumsub/websdk-react:

import SumsubWebSdk from '@sumsub/websdk-react';

function VerifyKyc({ accessToken, sumvinJwt, onComplete, onError }) {
  const expirationHandler = async () => {
    // Refetch a new access token when the current one expires.
    // `sumvinJwt` is your Sumvin session JWT (the same one used elsewhere
    // in the app for `x-juno-jwt`) — pass it in from your auth context.
    const res = await fetch('/v0/kyc/access-token', {
      method: 'POST',
      headers: { 'x-juno-jwt': sumvinJwt },
    });
    const { access_token } = await res.json();
    return access_token;
  };

  const handleMessage = (type) => {
    // When the user finishes uploads, advance your UI. Final approval is
    // delivered asynchronously by webhook — do not block on it here.
    if (
      type === 'idCheck.onApplicantSubmitted' ||
      type === 'idCheck.onApplicantResubmitted' ||
      type === 'idCheck.onApplicantActionCompleted'
    ) {
      onComplete();
    }
  };

  return (
    <SumsubWebSdk
      accessToken={accessToken}
      expirationHandler={expirationHandler}
      config={{ lang: 'en', theme: 'dark' }}
      options={{ addViewportTag: false, adaptIframeHeight: true }}
      onMessage={handleMessage}
      onError={onError}
    />
  );
}

For mobile apps use @sumsub/react-native-mobilesdk-module. The native SDK opens a full-screen verification flow rather than an iframe:

yarn add @sumsub/react-native-mobilesdk-module
# or
npm install @sumsub/react-native-mobilesdk-module

import SNSMobileSDK from '@sumsub/react-native-mobilesdk-module';

async function fetchAccessToken(sumvinJwt: string): Promise<string> {
  const res = await fetch('https://api.sumvin.com/v0/kyc/access-token', {
    method: 'POST',
    headers: { 'x-juno-jwt': sumvinJwt },
  });
  const { access_token } = await res.json();
  return access_token;
}

async function launchVerification(sumvinJwt: string, onComplete: () => void) {
  const accessToken = await fetchAccessToken(sumvinJwt);

  const sdk = SNSMobileSDK
    .init(accessToken, () => fetchAccessToken(sumvinJwt))   // 2nd arg: token expiration handler
    .withHandlers({
      onStatusChanged: (event) => {
        // The user has progressed through (or finished) the verification.
        // The launch() promise also resolves on close — see below.
        console.log('[Sumsub]', event.prevStatus, '→', event.newStatus);
      },
    })
    .withLocale('en')
    .build();

  try {
    const result = await sdk.launch();
    // SDK closed. Final approval comes from the Sumvin webhook —
    // do NOT block on this result for the verification outcome.
    // Just advance your UI; the user's KYC state will update via /v0/kyc/status.
    onComplete();
  } catch (err) {
    console.error('[Sumsub] launch error', err);
  }
}

iOS / Android native config required. The SDK needs camera and (optionally) NFC permissions in Info.plist and AndroidManifest.xml. Follow SumSub’s React Native module guide for the platform-specific build steps.

The @sumsub/react-native-mobilesdk-module JS package wraps native iOS/Android binaries that update independently. If you hit build errors after a SumSub change, bump to the latest tagged release and check the changelog — the JS layer can be stable while the underlying native pods/AARs need a fresh pod install or Gradle sync.

The token expiration handler is required for sessions that may exceed 10 minutes — SumSub calls it transparently to refresh the token. Wire it up via the expirationHandler prop on <SumsubWebSdk> for the Web React SDK, or as the second argument to SNSMobileSDK.init() for React Native. Without it, long-running verification sessions break mid-flow. This is the most common integration mistake.

Do not use /v0/kyc/sumsub/connect/authorize. That endpoint starts the SumSub ID Connect (OIDC cross-partner identity sharing) flow, which is a separate feature requiring distinct provisioning with SumSub. For the standard onboarding flow described here, you only need /v0/kyc/applicant and /v0/kyc/access-token.

4. Advance your UI on completion

When the SDK signals completion, the user has finished their part. Do not poll for approval here. SumSub’s review runs asynchronously (seconds to minutes); the result arrives via webhook to /v0/webhooks/kyc/sumsub/events and updates kyc_verified_at / kyc_rejected_at on the user. The completion signal differs by platform:

Web (@sumsub/websdk-react): the onMessage callback fires with idCheck.onApplicantSubmitted, idCheck.onApplicantResubmitted, or idCheck.onApplicantActionCompleted.
React Native (@sumsub/react-native-mobilesdk-module): the launch() promise resolves when the user closes the SDK; withHandlers({ onStatusChanged }) fires earlier as the user progresses.

In our B2C app, completion of the WebSDK simply submits the kyc_verification onboarding step; the user proceeds to the next step. Subsequent reads of /v0/user/me or /v0/kyc/status reflect the webhook-driven state once review completes. If you need to display the verification result on a “checking…” screen, call:

curl /v0/kyc/status?refresh=true \
  -H "x-juno-jwt: <token>"

{
  "status": "approved",
  "applicant_id": "65abc123def456",
  "verified_at": 1704067200000,
  "rejected_at": null,
  "reject_reason": null,
  "_links": { ... }
}

GET /v0/kyc/status?refresh=true returns 404 if the user has no SumSub applicant yet. If you skipped step 1 and the user has not yet interacted with the WebSDK, treat 404 as pending in your client. The non-refresh variant (?refresh=false, the default) returns 200 with locally cached state and never 404s.

5. Onboarding auto-advances

If the user is on the kyc_verification onboarding step when the webhook delivers an approved review, onboarding automatically advances to the next step. Re-fetch onboarding state after webhook delivery (or on the user’s next session):

curl /v0/user/me/onboarding/steps \
  -H "x-juno-jwt: <token>"

Hybrid Mode

1. Create an applicant

curl -X POST /v0/kyc/applicant \
  -H "x-juno-jwt: <token>"

{
  "applicant_id": "65abc123def456",
  "user_id": "usr_abc123",
  "already_existed": false,
  "_links": {
    "self": { "href": "/v0/kyc/applicant", "method": "POST" },
    "documents": { "href": "/v0/kyc/documents", "method": "POST" },
    "required-docs": { "href": "/v0/kyc/documents/required" },
    "status": { "href": "/v0/kyc/status" }
  }
}

2. Upload identity documents

curl -X POST /v0/kyc/documents \
  -H "x-juno-jwt: <token>" \
  -F "document_type=PASSPORT" \
  -F "country=GBR" \
  -F "file=@passport.jpg"

{
  "document_type": "PASSPORT",
  "country": "GBR",
  "side": null,
  "image_id": "img_abc123",
  "_links": {
    "self": { "href": "/v0/kyc/documents", "method": "POST" },
    "required-docs": { "href": "/v0/kyc/documents/required" },
    "applicant": { "href": "/v0/kyc/applicant", "method": "POST" },
    "status": { "href": "/v0/kyc/status" }
  }
}

3. Check all required documents are uploaded

curl /v0/kyc/documents/required \
  -H "x-juno-jwt: <token>"

{
  "steps": [
    {
      "step_type": "IDENTITY",
      "has_documents": true,
      "review_answer": null,
      "moderation_comment": null
    }
  ],
  "all_uploaded": true,
  "_links": {
    "self": { "href": "/v0/kyc/documents/required" },
    "documents": { "href": "/v0/kyc/documents", "method": "POST" },
    "status": { "href": "/v0/kyc/status" },
    "submit": { "href": "/v0/kyc/submit", "method": "POST" }
  }
}

4. Launch liveness-only SDK

Generate a liveness-scoped access token and initialize the SDK for the liveness step only:

curl -X POST /v0/kyc/access-token?level=liveness \
  -H "x-juno-jwt: <token>"

{
  "access_token": "_act-sbx-...",
  "expires_in": 600,
  "user_id": "usr_abc123",
  "_links": {
    "self": { "href": "/v0/kyc/access-token", "method": "POST" },
    "status": { "href": "/v0/kyc/status" }
  }
}

Pass the token to the SDK. The SDK opens directly to the liveness capture step — no document upload screens.

5. Submit for review

After the liveness step completes, submit the applicant for review:

curl -X POST /v0/kyc/submit \
  -H "x-juno-jwt: <token>"

{
  "status": "pending",
  "applicant_id": "65abc123def456",
  "_links": {
    "self": { "href": "/v0/kyc/submit", "method": "POST" },
    "status": { "href": "/v0/kyc/status" },
    "details": { "href": "/v0/kyc/details" }
  }
}

6. Poll for verification status

Same as WebSDK mode — poll the status endpoint with ?refresh=true until a terminal state is reached. GET /v0/kyc/status — Poll current status.

Document-Only Mode

1. Create an applicant

curl -X POST /v0/kyc/applicant \
  -H "x-juno-jwt: <token>"

{
  "applicant_id": "65abc123def456",
  "user_id": "usr_abc123",
  "already_existed": false,
  "_links": {
    "self": { "href": "/v0/kyc/applicant", "method": "POST" },
    "documents": { "href": "/v0/kyc/documents", "method": "POST" },
    "required-docs": { "href": "/v0/kyc/documents/required" },
    "status": { "href": "/v0/kyc/status" }
  }
}

2. Upload identity documents

curl -X POST /v0/kyc/documents \
  -H "x-juno-jwt: <token>" \
  -F "document_type=PASSPORT" \
  -F "country=GBR" \
  -F "file=@passport.jpg"

3. Check all required documents are uploaded

curl /v0/kyc/documents/required \
  -H "x-juno-jwt: <token>"

Confirm all_uploaded is true before submitting.

4. Submit for review

No liveness step is required. Submit directly after documents are uploaded:

curl -X POST /v0/kyc/submit \
  -H "x-juno-jwt: <token>"

5. Poll for verification status

Same as WebSDK mode — poll the status endpoint with ?refresh=true until a terminal state is reached. GET /v0/kyc/status — Poll current status.

KYC Modes

The verification mode is selected per integration server-side. Your frontend reads the mode from meta.kyc_mode on the kyc_verification onboarding step and renders the appropriate flow.

Mode	`meta.kyc_mode`	Document Upload	Liveness Check	When to Use
WebSDK	`"websdk"`	SDK handles	SDK handles	Default — simplest integration
Hybrid	`"hybrid"`	API upload (see below)	SDK liveness-only	Custom document capture UI
Document-only	`"document_only"`	API upload (see below)	None	Document verification without liveness

POST /v0/kyc/documents — Upload a document image. In WebSDK mode, you generate an access token and hand control to the SDK. In hybrid mode, you create an applicant, upload documents through the API, launch the SDK for liveness only, then submit for review. In document-only mode, you create an applicant, upload documents, and submit — no SDK initialization is needed.

meta.kyc_mode is always populated for the kyc_verification step. When the server-side configuration is missing, unreachable, or returns an unrecognized value, the API falls back to "websdk". Frontends do not need to defend against meta being null or kyc_mode being absent — branching on the three documented values is sufficient.

The mode can change between sessions if the configuration is updated server-side. Always read meta.kyc_mode from the current onboarding step rather than hardcoding a mode.

Per-organisation override

Partner organisations can pin their KYC mode independently of the global default by enabling the kyc feature on an environment:

PUT /v0/organisation/{org_id}/environments/{env_id}/features/kyc
Content-Type: application/json

{ "enabled": true, "config": { "mode": "websdk" } }

Allowed mode values: websdk, hybrid, document_only. The config object must either be omitted (or empty) or include a recognised mode value — supplying an unknown key (e.g. { "kyc_mode": "websdk" }) or an unknown value returns 422 Unprocessable Entity with error_code: KYC-422-001 and the allowed values listed in the response detail, so silent typos can’t mask an operator’s intent. If the feature row is disabled or no config is supplied, the global default applies. Operators can change a tenant’s mode at any time. Existing in-flight verification sessions are unaffected — the mode is read at the start of each onboarding state response, so a new selection takes effect from the next meta.kyc_mode your frontend reads.

KYC State

Reading Status

Fetch the current KYC status at any time:

GET /v0/kyc/status

Add ?refresh=true to pull the latest result from the verification provider instead of relying on the locally cached state. Use refresh=true during active verification when you need the most current status.

Response Shape

{
  "status": "in_progress",
  "applicant_id": "65abc123def456",
  "verified_at": null,
  "rejected_at": null,
  "reject_reason": null,
  "_links": {
    "self": { "href": "/v0/kyc/status" },
    "user": { "href": "/v0/user/me" },
    "refresh": { "href": "/v0/kyc/status?refresh=true" },
    "start-verification": { "href": "/v0/kyc/access-token", "method": "POST" }
  }
}

Field	Type	Description
`status`	string	Current KYC status (see KYC Statuses)
`applicant_id`	string or null	Provider applicant ID. Null if verification not started
`verified_at`	integer or null	Approval timestamp (epoch milliseconds)
`rejected_at`	integer or null	Rejection timestamp (epoch milliseconds)
`reject_reason`	string or null	Human-readable rejection or retry reason

The _links object includes a start-verification link when the status is pending or retry, guiding the client to begin or restart the verification flow.

KYC Lifecycle

Status transitions happen asynchronously. The API receives webhook events from the verification provider and updates the user’s KYC state. Your client discovers the new state by polling the status endpoint with ?refresh=true. GET /v0/kyc/status — Poll current status.

Endpoints

Generate SDK Access Token

POST /v0/kyc/access-token

Returns a short-lived access token for initializing the verification SDK in your frontend. Query parameters:

Parameter	Type	Default	Description
`level`	string	none	Set to `"liveness"` to generate a token scoped to the liveness-only verification step (hybrid mode)

Response: 200 OK

{
  "access_token": "_act-sbx-...",
  "expires_in": 600,
  "user_id": "usr_abc123",
  "_links": {
    "self": { "href": "/v0/kyc/access-token", "method": "POST" },
    "status": { "href": "/v0/kyc/status" }
  }
}

Field	Type	Description
`access_token`	string	Token to pass to the verification SDK
`expires_in`	integer	Token validity in seconds (default 600)
`user_id`	string	External user ID associated with this token

When level=liveness, the returned token restricts the SDK to the liveness verification step only. Use this in hybrid mode after documents have been uploaded via the API.

Check KYC Status

GET /v0/kyc/status

In React, useKycStatus() from our query patterns handles auth gating and shares status across components — pair it with a short refetchInterval while polling for approval.

Query parameters:

Parameter	Type	Default	Description
`refresh`	boolean	`false`	Fetch latest status from the verification provider

Response: 200 OK — see Response Shape above. When refresh=true:

If the user has no applicant record, returns 404 Not Found
If the provider is unreachable, returns 502 Bad Gateway
If KYC is approved and the user is on the kyc_verification onboarding step, onboarding auto-advances

Get KYC Details

GET /v0/kyc/details

Returns GDPR-compliant verification details including personal information (name only), document submission status, and rejection details. Query parameters:

Parameter	Type	Default	Description
`refresh`	boolean	`false`	Bypass the 5-minute cache and fetch from the provider

Response: 200 OK

{
  "status": "approved",
  "verified_at": 1704067200000,
  "rejected_at": null,
  "started_at": 1704060000000,
  "personal_info": {
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1990-05-15",
    "nationality": "GBR",
    "country_of_residence": "GBR"
  },
  "documents": [
    {
      "document_type": "PASSPORT",
      "country": "GBR",
      "status": "verified",
      "submitted_at": 1704061000000
    }
  ],
  "verification_complete": true,
  "verification_passed": true,
  "rejection": null,
  "_links": {
    "self": { "href": "/v0/kyc/details" },
    "refresh": { "href": "/v0/kyc/details?refresh=true" },
    "status": { "href": "/v0/kyc/status" },
    "user": { "href": "/v0/user/me" }
  }
}

Field	Type	Description
`status`	string	Current KYC status
`verified_at`	integer or null	Approval timestamp (epoch milliseconds)
`rejected_at`	integer or null	Rejection timestamp (epoch milliseconds)
`started_at`	integer or null	When verification was started (epoch milliseconds)
`personal_info`	object or null	Name and nationality extracted from documents
`documents`	array	Submitted documents with type, country, and status
`verification_complete`	boolean	Whether all required documents have been submitted
`verification_passed`	boolean	Whether verification passed all checks
`rejection`	object or null	Rejection details (see below)

Rejection object:

Field	Type	Description
`can_retry`	boolean	`true` if the user can resubmit, `false` for terminal rejections
`message`	string	Human-readable rejection reason

The personal_info fields other than name (date_of_birth, nationality, country_of_residence) are fetched from the provider on each request and are not stored locally. They are only available while the provider retains the applicant data.

Create Applicant

POST /v0/kyc/applicant

Creates a verification provider applicant for the user. Required before uploading documents in hybrid and document-only modes. This endpoint is idempotent. If an applicant already exists, it returns the existing applicant with a 200 OK response and already_existed: true. A new applicant returns 201 Created. Response: 200 OK / 201 Created

{
  "applicant_id": "65abc123def456",
  "user_id": "usr_abc123",
  "already_existed": false,
  "_links": {
    "self": { "href": "/v0/kyc/applicant", "method": "POST" },
    "documents": { "href": "/v0/kyc/documents", "method": "POST" },
    "required-docs": { "href": "/v0/kyc/documents/required" },
    "status": { "href": "/v0/kyc/status" }
  }
}

Field	Type	Description
`applicant_id`	string	Provider applicant ID
`user_id`	string	User ID associated with this applicant
`already_existed`	boolean	`true` if the applicant was already created

Upload Document

POST /v0/kyc/documents

Uploads an identity document for the user’s applicant. Used in hybrid and document-only modes to submit documents via the API. An applicant must exist before uploading documents — create one first. POST /v0/kyc/applicant — Create a KYC applicant.

Building a React UI? useUploadKycDocument() from our mutation patterns wraps the multipart upload and invalidates useKycRequiredDocs on success so your UI re-checks all_uploaded automatically.

Request: multipart/form-data

Field	Type	Required	Description
`document_type`	string	Yes	Document type (see Document Types)
`country`	string	Yes	Issuing country (ISO 3166-1 alpha-3, e.g. `GBR`)
`side`	string	No	Document side: `FRONT_SIDE` or `BACK_SIDE` (see Document Sides)
`file`	file	Yes	Document image or PDF. See Document Upload Constraints for size and MIME limits

Response: 201 Created

{
  "document_type": "ID_CARD",
  "country": "GBR",
  "side": "FRONT_SIDE",
  "image_id": "img_abc123",
  "_links": {
    "self": { "href": "/v0/kyc/documents", "method": "POST" },
    "required-docs": { "href": "/v0/kyc/documents/required" },
    "applicant": { "href": "/v0/kyc/applicant", "method": "POST" },
    "status": { "href": "/v0/kyc/status" }
  }
}

Field	Type	Description
`document_type`	string	Type of document uploaded
`country`	string	Issuing country (ISO 3166-1 alpha-3)
`side`	string or null	Document side, if provided
`image_id`	string or null	Provider image ID for the uploaded document

Check Required Documents

GET /v0/kyc/documents/required

Returns the required document steps for the user’s verification level and whether each step has documents uploaded. Use this to determine which documents still need to be uploaded before submission. An applicant must exist before checking required documents. POST /v0/kyc/applicant — Create a KYC applicant.

In React, useKycRequiredDocs() from our query patterns is the canonical “what’s left to upload?” hook — it auto-revalidates after useUploadKycDocument mutations and exposes all_uploaded for gating the submit button.

Response: 200 OK

{
  "steps": [
    {
      "step_type": "IDENTITY",
      "has_documents": true,
      "review_answer": null,
      "moderation_comment": null
    },
    {
      "step_type": "SELFIE",
      "has_documents": false,
      "review_answer": null,
      "moderation_comment": null
    }
  ],
  "all_uploaded": false,
  "_links": {
    "self": { "href": "/v0/kyc/documents/required" },
    "documents": { "href": "/v0/kyc/documents", "method": "POST" },
    "status": { "href": "/v0/kyc/status" }
  }
}

Field	Type	Description
`steps`	array	List of required document steps
`steps[].step_type`	string	Step type — see Required Step Types
`steps[].has_documents`	boolean	Whether documents have been uploaded for this step
`steps[].review_answer`	string or null	Review answer if reviewed (`GREEN`, `RED`, or null)
`steps[].moderation_comment`	string or null	Moderation comment if any
`all_uploaded`	boolean	`true` when all required steps have documents — ready for submission

When all_uploaded is true, the _links object includes a submit link:

{
  "_links": {
    "submit": { "href": "/v0/kyc/submit", "method": "POST" }
  }
}

Submit for Review

POST /v0/kyc/submit

Submits the applicant for review after all required documents have been uploaded. Used in hybrid mode (after document upload and liveness completion) and document-only mode (after document upload). An applicant must exist before calling submit; otherwise the call returns 404 Not Found (KYC-404-001). When required-document state can be fetched from the provider, the API checks all_uploaded first and returns 409 Conflict (KYC-409-001) if any required step is still missing documents — the same gate that backs the _links.submit field on GET /v0/kyc/documents/required. Always confirm all_uploaded is true before calling submit. If the required-docs lookup itself fails (provider unreachable), the API logs a warning and forwards the submission anyway — the provider then enforces its own completeness check and the call surfaces as 500 Internal Server Error (KYC-500-004) if the submission is rejected. Response: 200 OK

{
  "status": "pending",
  "applicant_id": "65abc123def456",
  "_links": {
    "self": { "href": "/v0/kyc/submit", "method": "POST" },
    "status": { "href": "/v0/kyc/status" },
    "details": { "href": "/v0/kyc/details" }
  }
}

Field	Type	Description
`status`	string	Submission status (`"pending"`)
`applicant_id`	string	Provider applicant ID

After submission, poll the status endpoint with ?refresh=true for the verification result. GET /v0/kyc/status — Poll current status.

Integration Patterns

WebSDK Flow

A typical frontend integration using WebSDK mode follows this sequence:

Check current status.
If pending or retry, create the applicant (idempotent), then generate an SDK access token.
Initialize the verification SDK with the token.
When the SDK signals completion, advance your UI. Approval is delivered asynchronously by webhook — do not block on it here.
On subsequent reads of /v0/kyc/status (or /v0/user/me), the new state is reflected once the webhook has been processed. If you need an immediate read-through to the provider, call /v0/kyc/status?refresh=true.

Endpoints used in this flow:

GET /v0/kyc/status — Check current status.
POST /v0/kyc/applicant — Create the SumSub applicant (idempotent).
POST /v0/kyc/access-token — Generate an SDK access token.

status = GET /v0/kyc/status

if status == "pending" or status == "retry":
    POST /v0/kyc/applicant         # idempotent — pins applicant_id server-side
    token = POST /v0/kyc/access-token
    launch_sdk(token.access_token)
    await sdk_completion_event()   # idCheck.onApplicantSubmitted (and friends)
    proceed_to_next_step()         # do NOT poll for approval here

# Later, on next status read (or after webhook fires):
status = GET /v0/kyc/status

if status == "approved":
    user_can_use_kyc_gated_features()
elif status == "rejected":
    show_rejection_message(status.reject_reason)
elif status == "retry":
    show_retry_prompt(status.reject_reason)

Why no polling loop? SumSub review is asynchronous and may take seconds to minutes. Blocking the user on a “checking…” spinner is poor UX. Instead, advance the user to the next step on WebSDK submission, and let the webhook deliver the final state. If you genuinely need a synchronous check (e.g., a verification result screen), use /v0/kyc/status?refresh=true which fetches live state from the provider on demand.

Hybrid Flow

A frontend integration using hybrid mode follows this sequence:

Check current status.
If pending or retry, create an applicant.
Upload each required document.
Check required documents to confirm all_uploaded is true.
Generate a liveness-scoped access token (?level=liveness).
Initialize the SDK with the liveness token — the SDK opens directly to the liveness step.
When the SDK signals completion, submit for review.
Poll status with ?refresh=true for the final result.

Endpoints used in this flow:

GET /v0/kyc/status — Check current status.
POST /v0/kyc/applicant — Create a KYC applicant.
POST /v0/kyc/documents — Upload a document image.
GET /v0/kyc/documents/required — Check required documents status.
POST /v0/kyc/access-token — Generate an SDK access token.
POST /v0/kyc/submit — Submit for review.

status = GET /v0/kyc/status

if status == "pending" or status == "retry":
    applicant = POST /v0/kyc/applicant

    for each document:
        POST /v0/kyc/documents (document_type, country, side, file)

    required = GET /v0/kyc/documents/required
    assert required.all_uploaded == true

    token = POST /v0/kyc/access-token?level=liveness
    launch_sdk(token.access_token)
    await sdk_completion()

    POST /v0/kyc/submit

    while status not in ["approved", "rejected"]:
        wait(3 seconds)
        status = GET /v0/kyc/status?refresh=true

if status == "approved":
    proceed_to_next_step()
elif status == "rejected":
    show_rejection_message(status.reject_reason)
elif status == "retry":
    show_retry_prompt(status.reject_reason)

Document-Only Flow

A frontend integration using document-only mode follows this sequence:

Check current status.
If pending or retry, create an applicant.
Upload each required document.
Check required documents to confirm all_uploaded is true.
Submit for review.
Poll status with ?refresh=true for the final result.

Endpoints used in this flow:

GET /v0/kyc/status — Check current status.
POST /v0/kyc/applicant — Create a KYC applicant.
POST /v0/kyc/documents — Upload a document image.
GET /v0/kyc/documents/required — Check required documents status.
POST /v0/kyc/submit — Submit for review.

status = GET /v0/kyc/status

if status == "pending" or status == "retry":
    applicant = POST /v0/kyc/applicant

    for each document:
        POST /v0/kyc/documents (document_type, country, side, file)

    required = GET /v0/kyc/documents/required
    assert required.all_uploaded == true

    POST /v0/kyc/submit

    while status not in ["approved", "rejected"]:
        wait(3 seconds)
        status = GET /v0/kyc/status?refresh=true

if status == "approved":
    proceed_to_next_step()
elif status == "rejected":
    show_rejection_message(status.reject_reason)
elif status == "retry":
    show_retry_prompt(status.reject_reason)

Polling for Approval

After the user completes the verification flow, the verification result arrives asynchronously via webhook. Poll the status endpoint with refresh=true at a reasonable interval until a terminal state is reached:

# First poll — may still be in_progress
curl /v0/kyc/status?refresh=true \
  -H "x-juno-jwt: <token>"

# Response: { "status": "in_progress", ... }

# Wait 3-5 seconds, then poll again
curl /v0/kyc/status?refresh=true \
  -H "x-juno-jwt: <token>"

# Response: { "status": "approved", "verified_at": 1704067200000, ... }

Avoid polling more frequently than every 3 seconds. Most verifications complete within 30 seconds to 2 minutes, but some require manual review and may take longer.

Handling Rejection

There are two rejection outcomes with different behaviours: Retry (status: "retry") — the user can fix and resubmit. The reject_reason field explains what needs correction. In WebSDK or hybrid mode, generate a new access token and let the user re-enter the SDK flow. In document-only mode, re-upload corrected documents and submit again. Rejected (status: "rejected") — terminal. The user cannot retry with the same identity documents. Display the reject_reason and direct them to contact support.

# Retry scenario
curl /v0/kyc/status \
  -H "x-juno-jwt: <token>"

{
  "status": "retry",
  "applicant_id": "65abc123def456",
  "verified_at": null,
  "rejected_at": null,
  "reject_reason": "Document image is blurry. Please resubmit a clear photo.",
  "_links": {
    "self": { "href": "/v0/kyc/status" },
    "user": { "href": "/v0/user/me" },
    "refresh": { "href": "/v0/kyc/status?refresh=true" },
    "start-verification": { "href": "/v0/kyc/access-token", "method": "POST" }
  }
}

When the status is retry, the _links object includes start-verification so your client can initiate a new verification attempt.

Onboarding Integration

KYC verification is one step in the onboarding flow. When KYC is approved and the user is on the kyc_verification onboarding step, the step auto-advances without requiring an explicit submit call. This happens in two scenarios:

Webhook-driven: The verification provider sends a webhook with an approval, and the API advances onboarding automatically.
Poll-driven: Your client polls the status endpoint with ?refresh=true, the API detects approval, and advances onboarding.

GET /v0/kyc/status — Poll current status. In both cases, re-fetch onboarding state afterward to render the next step:

curl /v0/user/me/onboarding/steps \
  -H "x-juno-jwt: <token>"

Error Handling

All error responses follow the RFC 7807 Problem Details format:

{
  "type": "https://api.sumvin.com/errors/kyc-500-002",
  "title": "KYC Token Generation Failed",
  "status": 500,
  "detail": "Failed to generate KYC access token",
  "instance": "/v0/kyc/access-token",
  "error_code": "KYC-500-002"
}

Status	Error Code	Meaning	Action
400 Bad Request	`KYC-400-001`	Invalid document file type	Use a supported format: JPEG, PNG, WebP, or PDF
400 Bad Request	`KYC-400-002`	File exceeds 10MB size limit	Reduce file size and retry
401 Unauthorized	`KYC-401-001`	Webhook signature validation failed	Internal: check webhook secret configuration
403 Forbidden	`KYC-403-001`	KYC verification required for this action	Complete KYC verification first
404 Not Found	`KYC-404-001`	No KYC applicant record found	Start verification (generate an access token) or create an applicant — see endpoints below
409 Conflict	`KYC-409-001`	Not all required documents uploaded	Upload remaining documents and re-check required status — see endpoints below
500 Internal Server Error	`KYC-500-001`	Internal error processing KYC	Retry; contact support if persistent
500 Internal Server Error	`KYC-500-002`	Failed to generate SDK access token	Retry; contact support if persistent
500 Internal Server Error	`KYC-500-003`	Document upload to provider failed	Retry the upload; contact support if persistent
500 Internal Server Error	`KYC-500-004`	Submission for review failed	Retry; contact support if persistent
502 Bad Gateway	`KYC-502-001`	Verification provider unavailable	Retry after a short delay

Examples by status

401 Unauthorized — missing or invalid auth headers (any KYC endpoint):

{
  "type": "https://api.sumvin.com/errors/usr-401-001",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid authentication credentials",
  "instance": "/v0/kyc/status",
  "error_code": "USR-401-001"
}

403 Forbidden — endpoint requires KYC and the user has not verified yet:

{
  "type": "https://api.sumvin.com/errors/kyc-403-001",
  "title": "KYC Verification Required",
  "status": 403,
  "detail": "KYC verification required for this action",
  "instance": "/v0/cards",
  "error_code": "KYC-403-001"
}

400 Bad Request — file exceeds the 10 MB limit on POST /v0/kyc/documents:

{
  "type": "https://api.sumvin.com/errors/kyc-400-002",
  "title": "File Too Large",
  "status": 400,
  "detail": "File size 12582912 exceeds maximum of 10485760 bytes (10MB).",
  "instance": "/v0/kyc/documents",
  "error_code": "KYC-400-002"
}

400 Bad Request — unsupported MIME type on POST /v0/kyc/documents:

{
  "type": "https://api.sumvin.com/errors/kyc-400-001",
  "title": "Invalid Document Type",
  "status": 400,
  "detail": "Unsupported file type: image/heic. Allowed: application/pdf, image/jpeg, image/png, image/webp",
  "instance": "/v0/kyc/documents",
  "error_code": "KYC-400-001"
}

409 Conflict — POST /v0/kyc/submit called before all required documents uploaded:

{
  "type": "https://api.sumvin.com/errors/kyc-409-001",
  "title": "KYC Not Ready For Submission",
  "status": 409,
  "detail": "Not all required documents have been uploaded. Check GET /v0/kyc/documents/required.",
  "instance": "/v0/kyc/submit",
  "error_code": "KYC-409-001"
}

502 Bad Gateway — provider unreachable on GET /v0/kyc/status?refresh=true or GET /v0/kyc/documents/required:

{
  "type": "https://api.sumvin.com/errors/kyc-502-001",
  "title": "KYC Provider Error",
  "status": 502,
  "detail": "Failed to fetch required documents status from KYC provider",
  "instance": "/v0/kyc/documents/required",
  "error_code": "KYC-502-001"
}

Recovery endpoints referenced above:

POST /v0/kyc/access-token — Generate an SDK access token.
POST /v0/kyc/applicant — Create a KYC applicant.
POST /v0/kyc/documents — Upload a document image.
GET /v0/kyc/documents/required — Check required documents status.

Reference Tables

KYC Statuses

Value	Description	Terminal?
`pending`	User has not started verification	No
`in_progress`	Verification started, awaiting result	No
`retry`	Additional information requested — user can resubmit	No
`approved`	Verification passed	Yes
`rejected`	Verification failed — user cannot retry	Yes

Polling stop conditions: approved and rejected are the only terminal states. Stop polling when status is one of those two values. pending (verification not started), in_progress (verification underway), and retry (additional info requested) are all non-terminal — keep polling until the status becomes terminal or the user takes a corrective action. retry requires user action. It is not auto-recoverable — show the reject_reason to the user and prompt them to resubmit. Polling will continue to return retry until the user re-enters the verification flow.

Required Step Types

The step_type field on each entry of GET /v0/kyc/documents/required is set by the verification provider and depends on the configured KYC level. Treat the value as an open string — the same level can return additional step types over time without an API version change. The values below are the ones the integration currently emits:

Value	Description
`IDENTITY`	Government-issued ID (passport, ID card, or driver’s license)
`SELFIE`	Selfie / liveness check
`PROOF_OF_ADDRESS`	Address verification document (utility bill, bank statement)

In WebSDK mode, the SDK fulfils these steps internally — your client typically only inspects this list in hybrid and document-only modes, where you upload the documents yourself.

Document Types

Value	Description
`PASSPORT`	International passport
`ID_CARD`	National identity card
`DRIVERS`	Driver’s license
`SELFIE`	Selfie / liveness photo (used when uploading via API rather than the SDK)
`PROOF_OF_ADDRESS`	Proof of address (utility bill, bank statement, etc.)

Document Sides

Some document types require both sides to be uploaded separately.

Value	Description
`FRONT_SIDE`	Front of the document
`BACK_SIDE`	Back of the document

Passports typically require only a single upload (no side). ID cards and driver’s licenses typically require both FRONT_SIDE and BACK_SIDE.

Document Upload Constraints

Validated server-side before forwarding to the verification provider. A request that violates any of these constraints fails with a 400 Bad Request (no provider call is made — see Error Handling).

Constraint	Value	Error code on violation
Maximum file size	10 MB per upload	`KYC-400-002`
Allowed MIME types	`image/jpeg`, `image/png`, `image/webp`, `application/pdf`	`KYC-400-001`
Allowed extensions	`.jpg`, `.jpeg`, `.png`, `.webp`, `.pdf`	`KYC-400-001`
Country format	ISO 3166-1 alpha-3 (e.g. `GBR`, `USA`, `DEU`) — passed through to the provider	Provider-side validation
Uploads per `step_type`	No fixed cap — re-upload appends another image. Both sides of an ID typically require one upload per side via the `side` parameter	—

Uploading a document_type=DRIVERS or document_type=ID_CARD typically requires both FRONT_SIDE and BACK_SIDE uploads to satisfy the corresponding IDENTITY step. Passports require a single upload with no side. These fields are populated on the user object after KYC verification:

Field	Type	Description
`first_name`	string or null	First name from identity document (set on approval)
`last_names`	string or null	Last name(s) from identity document (set on approval)
`kyc_verified_at`	integer or null	Approval timestamp (epoch milliseconds)
`kyc_rejected_at`	integer or null	Rejection timestamp (epoch milliseconds)

Next Steps

KYC is one step in the broader onboarding flow — read that guide for how the state machine advances when a verification lands, and the authentication reference for the JWT every KYC endpoint expects. KYC is the boundary between the identity and the attestation. Everything downstream — scopes, cards, spend — reads off what this step writes.

​Overview

​Quick Start

​WebSDK Mode

​1. Create the applicant (idempotent)

​2. Generate an SDK access token

​3. Embed the SumSub SDK

​4. Advance your UI on completion

​5. Onboarding auto-advances

​Hybrid Mode

​1. Create an applicant

​2. Upload identity documents

​3. Check all required documents are uploaded

​4. Launch liveness-only SDK

​5. Submit for review

​6. Poll for verification status

​Document-Only Mode

​1. Create an applicant

​2. Upload identity documents

​3. Check all required documents are uploaded

​4. Submit for review

​5. Poll for verification status

​KYC Modes

​Per-organisation override

​KYC State

​Reading Status

​Response Shape

​KYC Lifecycle

​Endpoints

​Generate SDK Access Token

​Check KYC Status

​Get KYC Details

​Create Applicant

​Upload Document

​Check Required Documents

​Submit for Review

​Integration Patterns

​WebSDK Flow

​Hybrid Flow

​Document-Only Flow

​Polling for Approval

​Handling Rejection

​Onboarding Integration

​Error Handling

​Examples by status

​Reference Tables

​KYC Statuses

​Required Step Types

​Document Types

​Document Sides

​Document Upload Constraints

​KYC-Related User Fields

​Next Steps

Overview

Quick Start

WebSDK Mode

1. Create the applicant (idempotent)

2. Generate an SDK access token

3. Embed the SumSub SDK

4. Advance your UI on completion

5. Onboarding auto-advances

Hybrid Mode

1. Create an applicant

2. Upload identity documents

3. Check all required documents are uploaded

4. Launch liveness-only SDK

5. Submit for review

6. Poll for verification status

Document-Only Mode

1. Create an applicant

2. Upload identity documents

3. Check all required documents are uploaded

4. Submit for review

5. Poll for verification status

KYC Modes

Per-organisation override

KYC State

Reading Status

Response Shape

KYC Lifecycle

Endpoints

Generate SDK Access Token

Check KYC Status

Get KYC Details

Create Applicant

Upload Document

Check Required Documents

Submit for Review

Integration Patterns

WebSDK Flow

Hybrid Flow

Document-Only Flow

Polling for Approval

Handling Rejection

Onboarding Integration

Error Handling

Examples by status

Reference Tables

KYC Statuses

Required Step Types

Document Types

Document Sides

Document Upload Constraints

KYC-Related User Fields

Next Steps