Session link options¶

Every endpoint that mints a session link — POST /v1/applicants/{externalUserId}/verifications, POST /v1/applicants/{externalUserId}/verification-sessions, POST /v1/applicants/{externalUserId}/ubos/{uboIndex}/spawn-kyc, POST /v1/applicants/{externalUserId}/ubos/{uboIndex}/regenerate-link — accepts the same set of presentation knobs. Pass them as query params (on the ?… of the request URL) on the URL-driven endpoints, or as fields in the JSON body on the body-driven endpoints (spawn-kyc, regenerate-link).

The hosted SDK reads these from the minted link's URL at runtime, so the user lands in a UI that's already pre-configured.

The knobs¶

Param	Type	Effect	Default
`lang`	ISO-639 code (`en`, `ru`, …)	Pins the SDK language. Empty → browser locale, then English.	unset
`theme`	`light` \| `dark` \| `system`	Pins light/dark; `system` follows the user's OS preference.	`system`
`returnUrl`	http(s) URL	Redirect target on either outcome. Must be a valid absolute URL — malformed values are dropped silently and the user lands on the SDK's terminal screen instead.	unset
`successUrl`	http(s) URL	Redirect target on terminal success only. Takes precedence over `returnUrl` for the success case.	falls back to `returnUrl`
`errorUrl`	http(s) URL	Redirect target on terminal error / final reject only. Takes precedence over `returnUrl` for the error case.	falls back to `returnUrl`

successUrl / errorUrl are the right choice when your post-flow UX differs — e.g. success goes back into your onboarding wizard, error goes to a "talk to support" page. Use plain returnUrl when both outcomes land on the same screen.

Examples¶

URL-driven (verification-sessions)¶

curl -X POST 'https://api.compliance.example/v1/applicants/user-12345/verification-sessions?verificationLevelName=KYC_01&lang=ru&theme=dark&returnUrl=https://acme.com/done' \
  -H 'X-Api-Key: pk_live_...' \
  -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production'

Split-redirect variant — success keeps the user in your wizard, error sends them to support:

curl -X POST 'https://api.compliance.example/v1/applicants/user-12345/verification-sessions?verificationLevelName=KYC_01&successUrl=https://acme.com/onboarding/step-3&errorUrl=https://acme.com/support/kyc-help' \
  -H 'X-Api-Key: pk_live_...' \
  -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production'

Body-driven (spawn-kyc on a UBO)¶

curl -X POST 'https://api.compliance.example/v1/applicants/acme-corp/ubos/0/spawn-kyc' \
  -H 'X-Api-Key: pk_live_...' \
  -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production' \
  -H 'Content-Type: application/json' \
  -d '{
        "ttlDays": 14,
        "lang": "ru",
        "theme": "dark",
        "returnUrl": "https://acme.com/ubo-done"
      }'

Notes¶

The user can still override lang and theme from within the SDK (language picker in the header, theme follows your theme query param as a starting state). Treat the query params as the default, not a lock.
Redirect URLs are not validated against an allowlist on the server — they only need to parse as a valid absolute http(s) URL. Don't pass user-controlled URLs without your own validation first.
All four URL fields share the same parser; if you accidentally pass returnUrl=javascript:… or a relative path, the field is silently dropped and the SDK falls back to its terminal screen.