> 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/api/verification-session.md).

# Verification session

### Creating a Verification Session in VOVE ID

#### Overview

The verification session in VOVE ID is initiated by the client's backend through a specific API call. This process is crucial for setting up the user's verification flow and involves creating or updating the user's information in the VOVE ID database.

#### Endpoint and Request

* **Base URL**: `https://api.voveid.com` or `https://api.voveid.net`
* **Endpoint**: `POST /v2/sessions`
* **Payload**: The request payload should include:
  * **refId**: This is the user's ID in the client's database. It's a mandatory field used to retrieve the user's verification status from VOVE ID's backend in the future. For users not registered in the client's system (non-registered users), the client should generate a UUID and include it in the request. It's the client's responsibility to store this ID for future reference.
  * **flowId** (optional): Custom verification flow identifier.
  * **user** (optional for IDV, mandatory for other flows): Details provided by the user in the client's application.
  * **forceCreation** (optional, default: `false`): When set to `true`, forces the creation of a new session even if an active session already exists for the user. By default, if an active session exists, the existing session token is returned instead of creating a new one.

#### Creating/Updating User and Session

* When the `POST /v2/sessions` endpoint is called with the required payload, it either creates a new user or updates an existing user in VOVE ID's database.
* By default, if an active session (open or in-progress) already exists for the user, the existing session is returned and extended. To force the creation of a new session, use the `forceCreation` parameter.
* A verification session is created for the user, and a session token is generated and returned in the response.

#### Handling the Session Token

* The returned session token should be securely passed to the frontend SDK to initiate the verification flow.
* The token is valid for 30 minutes. If it expires, the client can request a new one by making another `POST /v2/sessions` call.
* **Security Note**: This part of the verification session creation should be handled on your backend to ensure the secure use of the API key.
* In case of an error, appropriate error messages and codes will be returned for troubleshooting.

#### Example Request

```http
POST /v2/sessions
Content-Type: application/json
x-api-key: API_KEY

{
    "refId": "3eb8c91c-c866-4fcb-9805-67e8b45c7883", // mandatory
    "flowId": "d77bb134-dd51-4a30-97b0-9638f4f2edb1", // optional
    "forceCreation": false, // optional, default: false
    "user": { // optional
        "firstName": "Travis",
        "lastName": "Greenholt",
        "gender": "male",
        "dateOfBirth": "01-10-2000"
    }
}
```

#### Example Response

```
{
    "success": true,
    "token": "SESSION_TOKEN"
}
```

#### Conclusion

Creating a verification session is a critical step in VOVE ID's verification process. By following these guidelines, clients can ensure a smooth and secure verification experience for their users.

<br>