Create Onboarding Session

Creates a hosted onboarding (KYC) session for a customer against a product and returns the hostedUrl
you redirect the customer to. Use this instead of - or alongside - Submit Applicant for products that
use a hosted verification flow (typically Banks and Payments products).

Prerequisites: the customer and the product must already exist, and the product must be active.

Optional Fields

Field	Type	Description	Constraints
`sumSubToken`	`string`	An existing SumSub share token for the customer, used to prefill the hosted session. Omit it to have one generated for you	Nullable
`returnUrl`	`string (uri)`	Where the customer is redirected once the hosted flow finishes	Must be an absolute http/https URL

The body is optional - POST with no body is valid.

Response Fields (inside data)

Field	Type	Description
`customerId`	`string (uuid)`	Customer the session belongs to
`productId`	`string (uuid)`	Product the session was created for
`productType`	`string`	Product type - `Cards`, `Banks`, `Wallets`, `Exchange`, `Payments`
`hostedUrl`	`string (uri)`	The URL to redirect the customer to
`walletId`	`string (uuid), nullable`	Wallet the session belongs to (Banks products)
`status`	`string`	`ready` when `hostedUrl` is populated, otherwise `unavailable`
`sumSubTokenApplied`	`boolean`	Whether a SumSub token was applied. The token itself is never returned
`message`	`string`	Empty on success; the reason when the session is unavailable

When a hosted session is not available for the product, the call returns
409 ONBOARDING_SESSION_UNAVAILABLE with the reason in error.message - submit the applicant
details directly instead.

curl --location '/api/v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/products/5e91a0d4-2b77-4c1a-8d36-9ab0c1d2e3f4/onboarding' \ --header 'X-API-Key;' \ --header 'X-Signature;' \ --header 'X-Timestamp;' \ --header 'X-Nonce;' \ --header 'X-Body-Hash;' \ --header 'X-Idempotency-Key;' \ --header 'Content-Type: application/json' \ --data '{}'

{ "data": { "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "productId": "5e91a0d4-2b77-4c1a-8d36-9ab0c1d2e3f4", "productType": "Banks", "hostedUrl": "https://hosted-kyc.provider.com/session/7c9e6679-7425-40de-944b-e07fc1f90ae7", "walletId": "1b2c3d4e-5f60-4718-8293-a4b5c6d7e8f9", "status": "ready", "sumSubTokenApplied": true, "message": "" }, "requestId": "9f2c4b6e8a1d4f0cb7e35a91d2c46f80", "timestamp": "2026-08-22T10:30:00.123Z" }

Request

Responses