Get Image Identity Verification results via Webhooks

Webhooks provide an efficient way to get notified when an Image 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_document.done`	Triggered when an Image Identity Verification is completed

Example Webhook payload for a verified Image Identity Verification :

{
    "event_id": "d09f0367-d80a-309c-a2ed-7083991fc564",
    "event_name": "verification.identity_document.done",
    "event_time": "1348177752",
    "subscription_id": "d09f0367-d80a-309c-a2ed-7083991fc564",
    "subscription_description": "A great webhook",
    "sandbox": false,
    "data": {
        "identity_document": {
            "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
        }
    }
}

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

Retrieve detailed Image Identity Verification results

You can also obtain detailed verification results by calling a dedicated endpoint, with the id returned when requesting an Image Identity Verification:

GET /verifications/identity_documents/{id}

{
    "id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
    "workspace_id": "090b4f7e-25e8-423d-9387-741f6188ba7a",
    "created_at": "2025-03-24T13:32:26+00:00",
    "updated_at": "2025-03-24T13:32:46+00:00",
    "status": "failed",
    "status_codes": [
        "IDDV_1706",
        "IDDV_1707"
    ],
    "data_anonymized": false,
    "data": {
        "extracted_from_document": {
            "first_name": "John",
            "birth_name": "Doe",
            "last_name": "Doe",
            "born_on": "2024-01-18",
            "birth_location": "Paris",
            "gender": "f",
            "full_address": "13 RUE SAINT MARCELIN\nMARSEILLE 10E (13)",
            "type": "id_card",
            "issuing_country_code": "US",
            "issued_on": "2024-01-18",
            "expired_on": "2024-01-18",
            "document_number": "X4RTBPFW4",
            "mrz": {
                "line1": "IDFRASIAGRA<<<<<<<<<<<<<<<<<<<133039",
                "line2": "1002133008071GREGOIRE<<REMY8110228M4",
                "line3": "<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<"
            }
        }
    }
}

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

This endpoint returns also the data extracted from the ID document, such as the holder's name, the birth date or the document issuing country. Not all information listed in the example above is always available in the ID document. When a piece of information is missing, the endpoint will return null for that field.

After 7 days, Image 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": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
    "workspace_id": "090b4f7e-25e8-423d-9387-741f6188ba7a",
    "created_at": "2025-03-24T13:32:26+00:00",
    "updated_at": "2025-03-24T13:32:46+00:00",
    "status": "failed",
    "status_codes": [
        "IDDV_1706",
        "IDDV_1707"
    ],
    "data_anonymized": true,
    "data": {
        "extracted_from_document": {
            "first_name": null,
            "birth_name": null,
            "last_name": null,
            "born_on": null,
            "birth_location": null,
            "gender": null,
            "full_address": null,
            "type": null,
            "issuing_country_code": null,
            "issued_on": null,
            "expired_on": null,
            "document_number": null,
            "mrz": {
                "line1": null,
                "line2": null,
                "line3": null
            }
        }
    }
}

List all Image 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_documents

{
    "meta": {
        "next_cursor": "string"
    },
    "data": [
        {
            "id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
            "workspace_id": "090b4f7e-25e8-423d-9387-741f6188ba7a",
            "created_at": "2025-03-24T13:32:26+00:00",
            "updated_at": "2025-03-24T13:32:46+00:00",
            "status": "pending",
            "status_codes": [],
            "data_anonymized": false
        }
    ]
}