Create a verification session

Create a short-lived KYC session token from a trusted backend.

Creates or resumes a KYC verification session for a stable customer reference.

POST https://api.voveid.net/v2/sessions
x-api-key: vove_sandbox_replace_me
content-type: application/json

Call this endpoint only from your backend. Return the session token to the intended client; never expose the private API key.

Request

{
  "refId": "customer-7f3d",
  "flowId": "66f000000000000000000001",
  "forceCreation": false,
  "user": {
    "firstName": "Amina",
    "lastName": "Example",
    "idNumber": "X00000000",
    "gender": "female",
    "dateOfBirth": "01.02.1990"
  }
}

Body parameters

Field	Type	Required	Default	Description
refId	string	Yes	—	Stable identifier from your system. Persist it for webhook correlation and result retrieval.
flowId	string	No	Organization default	Custom KYC flow identifier.
forceCreation	boolean	No	false	When true, starts a new verification instead of resuming an existing open or in-progress session for the same refId. Use it only when the user must start over.
user	object	Flow-dependent	—	Required when information matching is enabled in the selected flow; otherwise optional prefill data.

User object

The following user fields can be provided. When information matching is enabled in the selected flow, provide every field that the flow is configured to compare.

Field	Type	Required	Description
firstName	string	No	Given name
lastName	string	No	Family name
idNumber	string	No	Identity-document number used to prefill the configured KYC flow
gender	string	No	Value accepted by the configured flow
dateOfBirth	string	No	Date of birth in DD.MM.YYYY format

TypeScript shape

type CreateVerificationSessionRequest = {
  refId: string;
  flowId?: string;
  forceCreation?: boolean;
  user?: {
    firstName?: string;
    lastName?: string;
    idNumber?: string;
    gender?: string;
    dateOfBirth?: string;
    [field: string]: unknown;
  };
};

Response

{
  "success": true,
  "token": "eyJ...redacted"
}

Field	Type	Description
success	boolean	Indicates that a session token was returned
token	string	Short-lived token passed to the intended client

type CreateVerificationSessionResponse = {
  success: true;
  token: string;
};

By default, an existing open or in-progress session for the same refId can be returned or extended. Set forceCreation to true only when the user must abandon that active attempt and start the verification again from the beginning.

The default token lifetime is 30 minutes. If it expires, request a new token from your backend.

cURL example

curl --request POST 'https://api.voveid.net/v2/sessions' \
  --header 'content-type: application/json' \
  --header 'x-api-key: vove_sandbox_replace_me' \
  --data '{
    "refId": "customer-7f3d",
    "flowId": "66f000000000000000000001",
    "forceCreation": false
  }'

Next steps

Start a client SDK, receive a signed webhook, and retrieve the result with GET /v2/users/{refId}.