KYC via web link

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. Contro manages the underlying identity verification, so there is nothing for you to integrate or configure beyond the endpoints below.

Flow

POST /partner/kyc-sessions         → { id, url, expiresAt }
User opens the URL and completes KYC on the Contro-hosted page
Verification result received → session status updated to "completed"
Poll GET /partner/kyc-sessions/{id} or listen for kyc_session.completed webhook
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"
  }'

const session = await contro.kycSessions.create({
  externalUserId: "user_42",
});
// session = { id: "ks_abc123", url: "https://kyc.contro.me/s/ks_abc123", expiresAt: "..." }

session = contro.kyc_sessions.create(external_user_id="user_42")
# session = { id: "ks_abc123", url: "https://kyc.contro.me/s/ks_abc123", expires_at: "..." }

const session = await fetch(`${BASE_URL}/partner/kyc-sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ externalUserId: "user_42" }),
}).then((r) => r.json());

// session = { id: "ks_abc123", url: "https://kyc.contro.me/s/ks_abc123", expiresAt: "..." }

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 Contro-hosted 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"

const session = await contro.kycSessions.retrieve(sessionId);
// session.status = "pending" | "completed" | "expired" | "failed"

session = contro.kyc_sessions.retrieve(session_id)
# session.status = "pending" | "completed" | "expired" | "failed"

const session = await fetch(`${BASE_URL}/partner/kyc-sessions/${sessionId}`, {
  headers,
}).then((r) => r.json());

// session.status = "pending" | "completed" | "expired" | "failed"

Session statuses

Status	Description
`creating`	Session is being provisioned
`pending`	Waiting for user to complete KYC
`completed`	KYC approved — ready to create cardholder
`expired`	Session expired (1 hour TTL)
`failed`	KYC 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"
  }'

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

cardholder = contro.cardholders.create(
    external_user_id="user_42",
    kyc_source="web",
    kyc_session_id="ks_abc123",
    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: "web",
    kycSessionId: "ks_abc123",
    email: "jane@example.com",
    phoneNumber: "+14155552671",
  }),
}).then((r) => r.json());

Key details

firstName and lastName are extracted automatically from the completed 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 re-checks the latest verification result synchronously as a fallback for delayed updates.

Required fields

Field	Type	Description
`externalUserId`	string	Your unique identifier for this user
`kycSource`	string	Must be `"web"`
`kycSessionId`	string	KYC session ID from step 1
`email`	string	Valid email address
`phoneNumber`	string	E.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 identity verification is performed.

Getting started

Core resources

Platform

KYC via web link

Flow

Step 1: Create a KYC session

Step 2: User completes KYC

Step 3: Check session status

Session statuses

Step 4: Create the cardholder

Key details

Required fields

Sandbox behavior

​Flow

​Step 1: Create a KYC session

​Step 2: User completes KYC

​Step 3: Check session status

​Session statuses

​Step 4: Create the cardholder

​Key details

​Required fields

​Sandbox behavior

Flow

Step 1: Create a KYC session

Step 2: User completes KYC

Step 3: Check session status

Session statuses

Step 4: Create the cardholder

Key details

Required fields

Sandbox behavior