> For the complete documentation index, see [llms.txt](https://docs.voveid.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voveid.com/docs/kyc-api/verification-session.md).

# 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.

```http
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

```json
{
  "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.                                                                                                                                                 |
| `governmentRegistryChecks` | array of objects | Flow-dependent | —                    | Identifiers for matching flow checks that allow API collection. Each entry contains `country`, `registry` and a string `identifier`. See the [Ghana guide](/docs/kyc-api/government-registry-check-ghana.md) for supported Ghana pairs and examples. |

### 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

```typescript
type CreateVerificationSessionRequest = {
  refId: string;
  flowId?: string;
  forceCreation?: boolean;
  governmentRegistryChecks?: Array<
    | { country: 'GH'; registry: 'CARD' | 'VOTER_ID' | 'PASSPORT'; identifier: string }
    | { country: 'NG'; registry: 'NIN' | 'BVN'; identifier: string }
  >;
  user?: {
    firstName?: string;
    lastName?: string;
    idNumber?: string;
    gender?: string;
    dateOfBirth?: string;
    [field: string]: unknown;
  };
};
```

## Response

```json
{
  "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 |

```typescript
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

```bash
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](/docs/sdks/compatibility.md), receive a [signed webhook](/docs/kyc-api/webhooks.md), and retrieve the result with [`GET /v2/users/{refId}`](/docs/kyc-api/get-user-verification.md).