Request a Video Identity Verification

On this page, you will learn how to initiate a new Video Identity Verification using the API.

To initiate the verification process, you need to send the person’s full name and a redirection URL, using the following endpoint:

POST /verifications/identity_videos

{
    "first_name": "John",
    "last_name": "Doe",
    "redirection_url": "https://redirectionurl.com",
    "face_recognition": false,
    "workspace_id": "090b4f7e-25e8-423d-9387-741f6188ba7a"
}

{
    "id": "89120884-d29a-4b1a-ac7b-a9e73a872795",
    "workspace_id": "090b4f7e-25e8-423d-9387-741f6188ba7a",
    "created_at": "2025-03-24T13:32:26+00:00",
    "updated_at": "2025-03-24T13:32:26+00:00",
    "status": "pending",
    "status_codes": [],
    "face_recognition": false,
    "data_anonymized": false,
    "verification_url": "https:\/\/id.ubble.ai\/add29f2e-9671-40b4-b7b3-77d263f62897",
    "data": {
        "extracted_from_document": {
            "full_name": null,
            "born_on": null,
            "type": null,
            "issuing_country_code": null
        },
        "evidence": {
            "document_front_image_url": null,
            "face_image_url": null
        }
    }
}

Query Param	Type	Description
first_name	string	The first name of the person whose identity needs to be verified. Note: The first name provided must match exactly as it appears on the ID document, as a consistency check will be performed. If multiple given names are listed on the document, you must provide only one of them.
last_name	string	The last name of the person whose identity needs to be verified. Note: The last name provided must match exactly as it appears on the ID document, as a consistency check will be performed. If both a birth name and a usage name are listed on the document, you must provide one of them, but not both.
redirection_url	string	The URL to redirect the person back to your application or website after the identity verification flow is complete.
face_recognition	boolean	Enhances verification by incorporating a facial scan to confirm that the user’s face matches the photograph on their ID document. This parameter is disabled by default.
pvid	boolean	Enhances verification by enabling the Certified Identity Verification flow, applying more restricted checks and stricter requirements than the default verification. This parameter is disabled by default. Learn more about the different types of Video Identity Verification here.
workspace_id	string	Scopes the verification to a specific workspace. Defaults to the main workspace if not specified.
min_age	integer	Sets the minimum accepted age for the document holder. If the holder’s age, calculated from the extracted date of birth, is lower than this value, the verification will fail with a dedicated status code.
max_age	integer	Sets the maximum accepted age for the document holder. If the holder’s age, calculated from the extracted date of birth, is higher than this value, the verification will fail with a dedicated status code.
prohibited_countries	integer	Sets the list of issuing countries that must be rejected. If the issuing country extracted from the document matches one of the configured countries, the verification will fail with a dedicated status code.
pre_selected_residence_country_code	string	Pre-selects the user's country of residence during the verification journey. The user can still change this value during the flow.
pre_selected_document_issuing_country_code	string	Pre-selects the issuing country of the identity document during the verification journey. The user can still change this value during the flow.
pre_selected_document_type	string	Pre-selects the type of identity document the user will present. The user can still change this value during the flow. Accepted values: `id_card`, `passport`, `residence_permit`, `driver_license`, `travel_document`.
pre_selected_locale	string	Pre-selects the language of the verification journey interface. The user can still change this value during the flow.

In the response, you'll find these important following values:

id: This value is required to retrieve the verification results.
verification_url: Share this URL with the person whose identity needs to be verified. They will use it to follow a process on mobile to upload the front and back of their ID document. Note that the verification link expires after 15 minutes.