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

• 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

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.