Get video identity verification results via Webhooks

Webhooks provide an efficient way to get notified when an identity verification has been completed, and to retrieve the related verification results.
For more details on setting up and managing Webhooks, please refer to this dedicated section.

To receive those notifications, subscribe to the following event:

Event	Description
`verification.identity_video.done`	Triggered when a video identity verification is complete

Example Webhook Payload for a verified video identity verification:

{
    "event_id": "d09f0367-d80a-309c-a2ed-7083991fc564",
    "event_name": "verification.identity_video.done",
    "event_time": "1348177752",
    "subscription_id": "c08h0287-c70a-213a-f2ed-9627309gb764",
    "subscription_description": "A great webhook",
    "sandbox": false,
    "data": {
        "identity_video": {
            "id": "a08d2986-2b7f-439c-9f10-d8d65b06bb9d",
            "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": "verified",
            "status_codes": [ ],
            "data_anonymized": false,
            "face_recognition": false
        }
    }
}

The status_codes array provides specific status codes in the case a verification is failed, and can be used for troubleshooting.

For more information on the statuses and error codes, refer to this section.

Retrieve detailed video identity verification results

You can also obtain detailed verification results by calling a dedicated endpoint, with the id returned when requesting a video identity verification:

GET /verifications/identity_videos/{id}

{
    "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": "failed",
    "status_codes": [
        6000,
        7000
    ],
    "face_recognition": false,
    "data_anonymized": false,
    "verification_url": "https://id.ubble.ai/2f3e833c-6cf8-4c39-9004-cfb0e048ef63",
    "data": {
        "extracted_from_document": {
            "full_name": "David Vincent",
            "born_on": "2025-03-24",
            "type": "driving_license",
            "issuing_country_code": "US"
        },
        "evidence": {
            "document_front_image_url": "https://storage-b.env.ubble.ai/ubble-ai/88bf48f0-ce4a-449c-9af1-f138a7e09392/ae1f813a-02cf-4ffc-bf71-d823ed74dc8d/bb603e2f-5de9-40f2-9631-8285a33c24c0/tight_crops/aaa.png?X-Amz-Date=20230327T163228Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=xxx",
            "face_image_url": "https://storage-b.ubble.ai/11-production-ubble-ai/CKQNCMWHRPGT/idv_01jezpmz01mvn7r1n9eg596v5k/9a873da8-2395-4b05-b9a6-56644dfe2e06/9dc6948e-23b8-4405-81f2-28dccc0d9a71/face_asset_generation_0_rtc_face_0_rtc_face/face_crop_41.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=h6aivdggwQIvVyGWnAEw%2F20241216%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20241216T100820Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=xxx"
        }
    }
}

Similar to the webhook, you will receive the verification status and any associated error codes if the verification was failed. For more information on the statuses and status codes, refer to this section.

This endpoint returns also additional information about the verification:

Extracted from document: The data extracted from the ID document, such as the full name, the issuing country of the document, or the image of the document.
Face image URL: You can also collect the image of the holder's face if you have requested it via the face-recognition parameter when initiating the video identity verification.

After 90 days, identity verification records are anonymized, meaning all personal or sensitive data associated with the verification request is permanently deleted.

If you attempt to retrieve any verification details beyond this retention period, fields containing sensitive data will return null, and the data_anonymized parameter will be set to true:

{
    "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": "failed",
    "status_codes": [
        6000,
        7000
    ],
    "face_recognition": false,
    "data_anonymized": true,
    "verification_url":  null,
    "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
        }
    }
}

Please note that extracted images of the identity document and the holder’s face are only accessible for 10 minutes.

List all video identity verification requests

To retrieve a list of all verification requests, you can call the following endpoint. You can filter by status or paginate the results based on your needs:

GET /verifications/identity_videos

{
    "meta": {
        "next_cursor": "string"
    },
    "data": [
        {
            "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": [],
            "data_anonymized": false,
            "face_recognition": false
        }
    ]
}