Skip to main content
The web link method lets you delegate KYC entirely to Contro. You request a hosted KYC session, redirect your user to the URL, and create the cardholder after the session completes. You never handle identity documents directly.

​
Flow

1. POST /partner/kyc-sessions         → { id, url, expiresAt }
2. User opens the URL and completes KYC on Sumsub-powered page
3. Sumsub webhook → session status updated to "completed"
4. Poll GET /partner/kyc-sessions/{id} or listen for kyc_session.completed webhook
5. POST /partner/cardholders           with kycSource: "web" + kycSessionId

​
Step 1: Create a KYC session

curl -X POST https://api.contro.me/v1/partner/kyc-sessions \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_42"
  }'
The response includes a url that you open or embed for your user. Sessions expire after 1 hour.

​
Step 2: User completes KYC

Open or embed the url in your application. The user completes identity verification on the Sumsub-powered page.

​
Step 3: Check session status

Poll the session status or subscribe to the kyc_session.completed webhook event. 
curl https://api.contro.me/v1/partner/kyc-sessions/ks_abc123 \
  -H "x-contro-api-key: $CONTRO_API_KEY"

​
Session statuses

StatusDescription
creatingSession is being provisioned
pendingWaiting for user to complete KYC
completedKYC approved — ready to create cardholder
expiredSession expired (1 hour TTL)
failedKYC verification was rejected

​
Step 4: Create the cardholder

Once the session status is completed, create the cardholder referencing the session: 
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": "web",
    "kycSessionId": "ks_abc123",
    "email": "jane@example.com",
    "phoneNumber": "+14155552671"
  }'

​
Key details

  • firstName and lastName are extracted automatically from the completed Sumsub verification.
  • Each session can only be used for one cardholder (enforced by a unique constraint). Attempting to reuse a session returns 409 Conflict.
  • The session must be completed before cardholder creation. If the session is still pending, the endpoint performs a synchronous check against Sumsub as a fallback for delayed webhooks.

​
Required fields

FieldTypeDescription
externalUserIdstringYour unique identifier for this user
kycSourcestringMust be "web"
kycSessionIdstringKYC session ID from step 1
emailstringValid email address
phoneNumberstringE.164 formatted phone number

​
Sandbox behavior

In sandbox mode, POST /partner/kyc-sessions returns a mock URL and the session auto-completes immediately. No real Sumsub interaction occurs.