# Verify ID Documents The ID Document Verification solution enables you to verify that a person's ID document is authentic, using photos or scans of the document. > **Information** > > To enable ID Document Verification, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). --- ## Before you start - Prepare to handle [statuses, attempts, and response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes.md). - [Configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md) and prepare to handle [webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/id-document-verification-webhooks.md). - The person whose document you want to verify must already have an [applicant profile](https://www.checkout.com/docs/business-operations/manage-identities/manage-applicants.md). ### Configuration When you request to enable ID Document Verification, your account manager provides you an ID Document Verification configuration ID, prefixed with `usj_`. This is different to your [Identity Verification](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities/using-the-api.md#Configuration) and [Face Authentication](https://www.checkout.com/docs/business-operations/manage-identities/authenticate-with-biometrics/using-the-api.md#Configuration) configuration IDs. You must provide this ID every time you create a verification. It configures the following elements of the solution: - The service level agreement for receiving the verification result from Checkout.com - The ID documents you want to accept, if supported by Checkout.com - The data you want to extract from documents --- ## How it works 1. The applicant provides images of their ID document 2. Create an ID document verification linked to the applicant's profile. 3. Create an attempt and upload the document images. 4. Checkout.com checks if: - The image quality is sufficient to process. - The images and the document are authentic. - The name the applicant provided matches the document. - The image files contain malware. 5. Checkout.com returns the result and a report. 6. Get the ID document verification to see the detailed result. 7. Get the report. --- ## Create a verification Call the [Create an ID document verification](https://api-reference.checkout.com/tag/ID-Document-Verification/#operation/create_id_document_verification) endpoint, and provide the following fields: - `applicant_id` – The applicant ID from the `id` field in the [Create an applicant](https://www.checkout.com/docs/business-operations/manage-identities/manage-applicants.md#Create_an_applicant) response. - `user_journey_id` – Your ID Document Verification configuration ID. - `declared_data.name` – Optionally, the name the applicant provided to compare to the name extracted from the document. **Production** `POST` `https://identity-verification.checkout.com/id-document-verifications` **Sandbox** `POST` `https://identity-verification.sandbox.checkout.com/id-document-verifications` ### Request example ```json { "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we", "declared_data": { "name": "Hannah Bret" } } ``` ### Response example ```json { "id": "iddv_tkoi5db4hryu5cei5vwoabr7we", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we", "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "status": "approved", "response_codes": [ { "code": 10000, "summary": "approved" } ], "declared_data": { "name": "Hannah Bret" }, "document": { "full_name": "Hannah Bret", "birth_date": "1994-10-15", "document_type": "ID", "document_issuing_country": "US", "front_image_signed_url": "https://storage-b.env/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/tight_crops/FRA-I5-Front-bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921906596.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163228Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=87d8467ab92cbad7c00171af28e613d495f3ff441ce0ea59dd013d68abc50555" }, "_links": { "self": { "href": "https://identity-verification.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we" }, "applicant": { "href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we" } } } ``` The response returns the ID document verification ID in the `id` field, prefixed with `iddv_`. You need this to create an attempt. The ID document verification status changes to `created` and you receive an [ID document verification created](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/id-document-verification-webhooks.md) webhook. --- ## Create an attempt Call the [Create an ID document verification attempt](https://api-reference.checkout.com/tag/ID-Document-Verification/#operation/create_id_document_verification_attempt) endpoint, and provide the ID document verification ID from the Create an ID document verification response as the `{id_document_verification_id}` path parameter. Provide the following in the request body: - `document_front` – The image of the front of the document. - `document_back` – Optionally, the image of the back of the document, if relevant. ### Image format Images must not exceed 10MB in size and must be in one of the following formats: - JPEG - PDF - PNG **Production** `POST` `https://identity-verification.checkout.com/id-document-verifications/{id_document_verification_id}/attempts` **Sandbox** `POST` `https://identity-verification.sandbox.checkout.com/id-document-verifications/{id_document_verification_id}/attempts` ### Request example ```json { "document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD…\n" } ``` ### Response example ```json { "id": "datp_tkoi5db4hryu5cei5vwoabr7we", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "status": "completed", "response_codes": [], "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/id-document-verifications/datp_tkoi5db4hryu5cei5vwoabr7we" } } } ``` The response returns the attempt ID in the `id` field, prefixed with `datp_`. > **Note** > > If an attempt is unsuccessful and the applicant needs to retry, you can create new attempts. **Successful attempt** The following table describes the process of a successful attempt: | Scenario | Description | | --- | --- | | Checkout.com checks image quality | The ID document verification status and attempt status change to `quality_checks_in_progress`. | | Checkout.com checks for authenticity | The ID document verification status and attempt status change to `checks_in_progress`.

You receive an [ID document verification started](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/id-document-verification-webhooks.md) webhook. | | Verification is complete | The attempt status changes to `completed`.

The ID document verification status changes to one of the following:

- `approved` – The document is verified successfully.
- `declined` – The document is declined. If you want to enable the applicant to retry, create a new ID document verification.

You receive an [ID document verification checks completed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/id-document-verification-webhooks.md) webhook. | **Unsuccessful attempt** An attempt may be unsuccessful due to the following scenarios: | Scenario | Description | | --- | --- | | Checks inconclusive | The ID document verification status changes to `retry_required`.

The attempt status changes to `checks_inconclusive`.

You receive an [ID document verification checks inconclusive](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/id-document-verification-webhooks.md) webhook.

You need to create a new attempt with different images of the document. | | Image quality insufficient | The ID document verification status changes to `retry_required`.

The attempt status changes to `quality_checks_aborted`.

You need to create a new attempt with different images of the document. | | Attempt forcibly closed when new attempt created | The attempt status changes to `terminated`.

You receive an [ID document verification closed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/id-document-verification-webhooks.md) webhook.

You need to create a new attempt with different images of the document. | > **Information** > > You can use the response codes returned in webhooks to implement your own business logic. > > Sharing guidance from the response codes with the applicant can help the next attempt succeed. For example, if the applicant's data connection is poor, let them know so they can try to improve it. ### Manage attempts You can manage attempts using the following endpoints: - [Get ID document verification attempts](https://api-reference.checkout.com/tag/Identity-Verification/#operation/list_attempts_id_document_verification) – Retrieve all attempts for a verification. - [Get an ID document verification attempt](https://api-reference.checkout.com/tag/ID-Document-Verification/#operation/get_id_document_verification_attempt) – Retrieve the details about a specific attempt. --- ## Get the verification You can get the details of the ID document verification at any time. For example, to check the status or details of an attempt. When the result is available, it is returned in the response. Call the [Get an ID document verification](https://api-reference.checkout.com/tag/ID-Document-Verification/#operation/retrieve_id_document_verification) endpoint, and provide the ID document verification ID as the `{id_document_verification_id}` path parameter. **Production** `GET` `https://identity-verification.checkout.com/id_document_verifications/{id_document_verification_id}` **Sandbox** `GET` `https://identity-verification.sandbox.checkout.com/id_document_verifications/{id_document_verification_id}` ### Response example ```json { "id": "iddv_tkoi5db4hryu5cei5vwoabr7we", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we", "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "status": "approved", "response_codes": [ { "code": 10000, "summary": "approved" } ], "declared_data": { "name": "Hannah Bret" }, "document": { "full_name": "Hannah Bret", "birth_date": "1994-10-15", "document_type": "ID", "document_issuing_country": "US", "front_image_signed_url": "https://storage-b.env/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/tight_crops/FRA-I5-Front-bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921906596.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163228Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=87d8467ab92cbad7c00171af28e613d495f3ff441ce0ea59dd013d68abc50555" }, "_links": { "self": { "href": "https://identity-verification.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we" }, "applicant": { "href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we" } } } ``` The response returns: - The ID document verification status - One or more response codes if the status is `approved`, `declined`, `retry_required` If the result is available, it also returns the document data and the best image captured of the document, in the `documents` object. --- ## Get the report When the ID document verification status is `approved` or `declined` and the report is available, you receive an [ID document verification report created](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/id-document-verification-webhooks.md#Successful_verification) webhook. Call the [Get ID document verification report](https://api-reference.checkout.com/tag/ID-Document-Verification/#operation/pdf_id_document_verification) endpoint, and provide the ID document verification ID as the `{id_document_verification_id}` path parameter. **Production** `GET` `https://identity-verification.checkout.com/id-document-verifications/{id_document_verification_id}/pdf-report` **Sandbox** `GET` `https://identity-verification.sandbox.checkout.com/id-document-verifications/{id_document_verification_id}/pdf-report` ### Response example ```json { "value": { "pdf_report": "https://www.example.com/pdf" } } ``` The response returns a URL where you can download the report. ### Remove personal data If an applicant requests that you remove their personally identifiable information (PII) from their ID document verification under the GDPR, you can use the [Anonymize an ID document verification](https://api-reference.checkout.com/tag/ID-Document-Verification/#operation/anonymize_id_document_verification) endpoint. You receive an [ID document verification anonymized](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/id-document-verification-webhooks.md) webhook. ### Audits If the ID document verification is later audited and the status updated, you receive an [ID document verification audit completed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/id-document-verification-webhooks.md) webhook.