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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.voveid.com/docs/api/verification-session.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.