Skip to main content

Web SDK Link

A Web SDK Link is a hosted, one-time verification link you can send an end user instead of integrating the IDV API yourself. The user opens the link in their browser, completes verification on a hosted page, and the result is recorded against the flowId and groupId the link was generated for. Your merchant secret is never exposed to the browser.

This requires a flow that belongs to a group — see Flows & Groups if you haven't created these yet.

  1. Open the Configuration page and select the flow you want to use.
  2. Click Generate Web SDK Link.
  3. Enter a User ID — your own identifier for the end user (this becomes externalUserId/userId for the session).
  4. Select a Group containing this flow. If none exist, create one first on the Groups page.
  5. Click generate. You'll get a shareable link and a QR code — send the link to the user, or have them scan the QR code on a mobile device.

POST /v2/sdk/session/web-sdk-link​

Accepts the same authentication as /v2/idv/verify (Basic Auth with your merchant credentials, or a portal session).

Request Body​

{
  "userId": "user-12345",
  "groupId": "group_e5f6g7h8",
  "flowId": "flow_a1b2c3d4"
}

All three fields are required strings. The API validates that flowId and groupId belong to your merchant account, and that the flow is a member of that group.

Example​

curl -X POST 'https://api2.cycurid.com/v2/sdk/session/web-sdk-link' \
  -u '{{merchantApiKey}}:{{merchantSecret}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user-12345",
    "groupId": "group_e5f6g7h8",
    "flowId": "flow_a1b2c3d4"
  }'

Response​

{
  "url": "https://websdk.cycurid.com?iswebsdklink=true&token=<one-time-token>"
}

The link token is valid for 10 minutes and can only be exchanged once.

Error Responses​

StatusMeaning
400userId, groupId, or flowId missing or not a string
404Flow not found for your merchant account
404Group not found for your merchant account
400Flow is not a member of the specified group
  1. The hosted page reads the token query parameter and calls POST /v2/sdk/session/exchange with { "token": "..." } — no authentication required for this call.
  2. The backend validates the token (unused, not expired), applies geo-blocking (checking both your account-wide blocked countries and the flow's own geo-blocked list), and creates a session.
    • If the detected country is blocked, this call returns 403 with { "error": "geo_blocked", "detectedCountry": "...", "message": "..." }.
  3. On success, the exchange returns a short-lived (10 minute) access token along with the flow's resolved configuration:
{
  "access_token": "...",
  "session_id": "...",
  "sdk_id": "...",
  "is_sandbox": false,
  "expires_in": 600,
  "userId": "user-12345",
  "groupId": "group_e5f6g7h8",
  "flowId": "flow_a1b2c3d4",
  "defaultFields": { "...": true },
  "defaultDocumentTypes": ["PASSPORT"],
  "countryOverrides": [],
  "biometricType": "selfie",
  "documentUploadType": "fileUpload"
}
  1. The hosted page renders the verification form based on defaultFields/defaultDocumentTypes/biometricType, then calls POST /v2/idv/verify directly from the browser using access_token as a Bearer token (see Authentication).

Biometric & Document Capture Modes​

biometricType and documentUploadType tell the hosted page how to capture the applicant's selfie and documents, based on the flow's configuration:

biometricTypeHosted Page Behavior
selfiePrompts the user to upload a static selfie image
live selfieCaptures a selfie live via the device camera
livenessRuns a liveness check (e.g. a guided head movement) via the device camera
documentUploadTypeHosted Page Behavior
fileUploadUser selects an existing image/PDF file for each document
fileCaptureUser captures each document live via the device camera
note

These values only affect how the hosted page captures input. The resulting request to /v2/idv/verify is unchanged either way — the captured biometric is always submitted as the selfie field, and documents are always submitted under their standard field names (passportFront, driversFront, etc.). See File Upload Fields.

Checking the Result​

Because the user completes verification on a hosted page, your server isn't in the request path and doesn't receive the /v2/idv/verify response. Poll the session instead.

GET /v2/sdk/session/verification-result/:sessionId​

Returns the current state of a Web SDK Link session.

Authentication​

Basic Authentication with your merchant credentials:

  • Username: {{merchantApiKey}}
  • Password: {{merchantSecret}}
Authorization: Basic base64(merchantApiKey:merchantSecret)

Path Parameters​

FieldTypeRequiredDescription
sessionIdstringYesThe session_id returned by POST /v2/sdk/session/exchange.

Example​

curl 'https://api2.cycurid.com/v2/sdk/session/verification-result/4a98055c-4398-42fe-ad37-578dc1310b22' \
  -u '{{merchantApiKey}}:{{merchantSecret}}'

Response​

{
  "session_id": "4a98055c-4398-42fe-ad37-578dc1310b22",
  "user_id": "user-12345",
  "status": "success",
  "result": "...",
  "type": "verification",
  "created_at": "2026-08-14T09:20:11.000Z",
  "completed_at": "2026-08-14T09:22:55.000Z",
  "duration_seconds": 164,
  "metadata": null
}
statusMeaning
pendingThe user has not finished yet. Keep polling.
successVerification completed successfully.
failedVerification completed but did not pass.
expiredThe session timed out before the user finished.

Sessions are scoped to your merchant account, so a session belonging to another merchant returns 404 rather than revealing that it exists.

Error Responses​

StatusMeaning
400sessionId missing, or credentials that don't match
401No credentials supplied
404No session with that ID for your merchant account
Result vs. applicant record

This endpoint reports on one session. For the applicant's full history — every attempt, their extracted document data, and their current status across groups — use the Applicant Lookup API.

Next Steps​