# Verify identities using the API The Identity Verification solution enables you to verify the identity of a physical person applying to use your services. This helps you meet compliance requirements and reduce the risk of fraud. The applicant captures video of their ID document and face. Checkout.com checks if the document is genuine and matches the person in the video, and shares the result and a full report. > **Information** > > To enable Identity 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 - [Set up an authentication mechanism](https://www.checkout.com/docs/developer-resources/api/manage-api-keys.md) for your API requests, using OAuth 2.0 or API keys. - Integrate Identity Verification in your [web app](https://www.checkout.com/docs/business-operations/manage-identities/integrate-via-web.md) or [mobile app](https://www.checkout.com/docs/developer-resources/sdks/identities-sdks.md). - [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 subscribe to [Identity Verification webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Identity_Verification). - [Create an applicant profile](https://www.checkout.com/docs/business-operations/manage-identities/manage-applicants.md). ### Configuration When you request to enable Identities, your account manager provides you an Identity Verification configuration ID, prefixed with `usj_`. 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 result from Checkout.com - ID documents: - The documents you want to accept, if supported by Checkout.com - Whether you require one document or two – primary and secondary - The data you want to extract from documents - Whether you require a video of the applicant's face - Processing type: - Fast – Highly automated processing, with human review if required - Expert – Systematic human review - SDK integration --- ## How it works 1. Create an identity verification linked to the applicant's profile. 2. Create an attempt. 3. Redirect the applicant to the attempt URL. 4. View the identity verification to see the result. 5. Download the identity verification report. 6. If requested, you can remove the applicant's personal details from the identity verification. > **Information** > > To test your integration, see [Identity Verification testing](https://www.checkout.com/docs/developer-resources/testing/identity-verification-testing.md). --- ## Create a verification To create an identity verification, you must have already created a profile for the applicant. You need the applicant ID either from the [Dashboard](https://www.checkout.com/docs/business-operations/manage-identities/manage-applicants/using-the-dashboard.md#View_an_applicant_ID) or 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. Call the [Create an identity verification](https://api-reference.checkout.com/tag/Identity-Verification/#operation/create_identity_verification) endpoint, and provide the following fields: - `applicant_id` – The applicant ID, prefixed with `aplt_`. - `declared_data.name` – The applicant's name. - `user_journey_id` – The configuration ID you want to apply to the verification. **Production** `POST` `https://identity-verification.checkout.com/identity-verifications` **Sandbox** `POST` `https://identity-verification.sandbox.checkout.com/identity-verifications` ### Request example ```json { "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "declared_data": { "name": "Hannah Bret" }, "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we" } ``` ### Response example ```json { "id": "idv_tkoi5db4hryu5cei5vwoabr7we", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we", "status": "created", "response_codes": [], "declared_data": { "name": "Hannah Bret", "birth_date": "1994-10-15" }, "documents": [], "_links": { "self": { "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we" }, "applicant": { "href": "https://identity-verification.checkout.com/applicants/aplt_lkoi5db4hryu5cei5vwoabqere" } } } ``` If successful the response returns the verification ID in the `id` field, prefixed with `idv_`. You need this to create an attempt. The identity verification status changes to `created` and you receive an [Identity verification created](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_created.md) webhook. --- ## Create an attempt To create an identity verification attempt, the identity verification status must be one of the following: - `created` - `pending` - `capture_in_progress` - `retry_required` Call the [Create an identity verification attempt](https://api-reference.checkout.com/tag/Identity-Verification/#operation/create_attempt) endpoint, and provide the verification ID from the `Create a verification` response as the `{identity_verification_id}` path parameter. Provide the following fields in the request body: - `redirect_url` – Provide the URL to redirect the applicant to after they complete the verification. For example, your success or failure URL. - `client_information.pre_selected_residence_country` – Optionally, the applicant's country of residence. - `client_information.pre_selected_language` – Optionally, the language to use for the user interface (UI). > **Information** > > Providing the applicant's country of residence shortens the verification journey and improves the experience because they do not have to select their country manually. **Production** `POST` `https://identity-verification.checkout.com/identity-verifications/{identity_verification_id}/attempts` **Sandbox** `POST` `https://identity-verification.sandbox.checkout.com/identity-verifications/{identity_verification_id}/attempts` ### Request example ```json { "redirect_url": "https://myweb.site?query-param=hello", "client_information": { "pre_selected_residence_country": "FR", "pre_selected_language": "en-US" } } ``` ### Response example ```json { "id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "client_information": { "pre_selected_residence_country": "FR", "pre_selected_language": "en-US" }, "redirect_url": "https://myweb.site?query-param=hello", "status": "pending_redirection", "response_codes": [ ], "_links": { "verification_url": { "href": "https://idv.checkout.com/4hryu5cei5/" }, "self": { "href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_01j58p8rw1hvterhqt66xn6js2/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ" } } } ``` The response returns: - The attempt ID in the `id` field, prefixed with `iatp_` - The attempt URL, which is valid for 15 minutes, in the `verification_url` field - The attempt status `pending_redirection` For SDK integration only, the response also returns a `client_secret`, which you need to authorize the verification in the SDK. For example, `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9`. The identity verification status changes to `pending` and you receive an [Identity verification opened](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_opened.md) webhook. --- ## Redirect the applicant For web integration, redirect the applicant to the attempt URL, which is valid for 15 minutes. For SDK integration, pass the following to the SDK: - The attempt URL, which is valid for 15 minutes - The `client_secret`, which is valid for 48 hours, to authorize the verification > **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 | | --- | --- | | Applicant starts the attempt | The verification and attempt statuses change to `capture_in_progress`.

You receive an [Identity verification started](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_started.md) webhook.

When successfully completed, the attempt status changes to `completed`.

You receive an [Identity verification capture completed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_capture_completed.md) webhook. | | Checkout.com processes the verification | The identity verification status changes to `checks_in_progress`.

Recommended action – You can ask the applicant to perform additional checks or to wait for the result.

When processing is complete, you receive an [Identity verification checks completed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_checks_completed.md) webhook.

You may receive the checks completed webhook simultaneously with the capture completed webhook. | | Result is available | The identity verification status changes to one of the following:

- `approved` – The identity verification is successful.
- `declined` – The identity verification is declined. If you want to enable the applicant to retry, create a new verification.

You receive an [Identity verification report created](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_report_created.md) webhook. | **Unsuccessful attempt** An attempt may be unsuccessful due to the following scenarios: | Scenario | Description | | --- | --- | | Attempt URL expires | The attempt status changes to `expired`.

You receive an [Identity verification link expired](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_link_expired.md) webhook.

Recommended action – Create a new attempt. | | Applicant refuses the verification | The identity verification status changes to `refused`.

The attempt status changes to `capture_refused`.

You receive an [Identity verification capture refused](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_capture_refused.md) webhook.

Recommended action – Suggest an alternative verification method to the applicant. | | Applicant drops out of the attempt | The attempt status changes to `capture_aborted`.

You receive an [Identity verification capture aborted](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_capture_aborted.md) webhook.

Recommended action – You can create a new attempt. | | Applicant needs to retry | The identity verification status changes to `retry_required`.

You receive an [Identity verification retry requested](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_retry_requested.md) webhook.

When you create a new attempt, the status of the previous attempt changes to `terminated`.

You receive an [Identity verification closed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_closed.md) webhook, followed by an [Identity verification reset](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_reset.md) webhook.

Recommended action – Redirect the applicant to the new attempt URL. | | Result is inconclusive | The identity verification status changes to `inconclusive`.

The attempt status changes to `checks_inconclusive`.

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

Recommended action – You can create a new attempt. | > **Information** > > You can use the response codes returned in webhooks to implement your own business logic. > > We recommend sharing guidance from response codes with applicants to help the next attempt succeed. For example, if the applicant's data connection is poor, they may be able to improve it. ### View attempts You can retrieve identity verification attempts using the following endpoints: - [Get identity verification attempts](https://api-reference.checkout.com/tag/Identity-Verification/#operation/list_attempts) – View all attempts for a verification. - [Get an identity verification attempt](https://api-reference.checkout.com/tag/Identity-Verification/#operation/list_attempts) – View the details of a specific attempt. --- ## Retrieve a verification You can retrieve the identity verification at any time. For example, to check the status or details of an attempt. When the result is available, it's returned in the API response. Call the [Get an identity verification](https://api-reference.checkout.com/tag/Identity-Verification/#operation/retrieve_identity_verification) endpoint, and provide the verification ID as the `{identity_verification_id}` path parameter. **Production** `GET` `https://identity-verification.checkout.com/identity-verifications/{identity_verification_id}` **Sandbox** `GET` `https://identity-verification.sandbox.checkout.com/identity-verifications/{identity_verification_id}` ### Response example ```json { "id": "idv_tkoi5db4hryu5cei5vwoabr7we", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "user_journey_id": "usj_5hxpdwegjcbujpth3wdo55d3vm", "status": "approved", "response_codes": [ { "code": 10000, "summary": "approved" } ], "verified_identity": { "full_name": "Hannah Bret", "birth_date": "1994-10-15" }, "declared_data": { "name": "Hannah Bret", "birth_date": "1994-10-15" }, "documents": [ { "full_name": "Hannah Bret", "birth_date": "1994-10-15", "document_type": "ID", "document_issuing_country": "US", "front_image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/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" } ], "face": { "image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4" }, "phone_number": { "country_code": "+1", "number": "2068133616" }, "redirect_url": "https://example.com?query-param=hello", "_links": { "self": { "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we" }, "verification_url": { "href": "https://idv.checkout.com/4hryu5cei5/" } } } ``` The response returns: - The identity verification status - One or more response codes if the status is `approved`, `declined`, `inconclusive`, `pending`, `refused`, `retry_required` If the result is available, it also returns: - Information about the applicant's identity in the `verified_identity` object - The applicant's ID document data and the best image captured of the document, in the `documents` object - The best image captured of the applicant's face in the `face` object --- ## Download the report A detailed report for the identity verification is provided in PDF format. When the report is ready, you receive an [Identity verification report created](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_report_created.md) webhook. Call the [Get identity verification report](https://api-reference.checkout.com/tag/Identity-Verification/#operation/pdf_identity_verification) endpoint, and provide the verification ID as the `{identity_verification_id}` path parameter. **Production** `GET` `https://identity-verification.checkout.com/identity-verifications/{identity_verification_id}/pdf-report` **Sandbox** `GET` `https://identity-verification.sandbox.checkout.com/identity-verifications/{identity_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. > **Information** > > [Download a sample report](https://www.checkout.com/docs/files/Sample_Identity_verification_report.pdf).
> > If using Safari, hold down the _Option_ key when selecting the link to download the file. ### Audits If the identity verification is later audited and the status updated, you receive an [Identity verification audit completed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_audit_completed.md) webhook. --- ## Remove personal details If requested by an applicant under the General Data Protection Regulation (GDPR), you can remove the following personally identifiable information (PII) from the identity verification: - External applicant name – The name you have on record for the applicant. - Applicant email – The applicant's email address. - All information on the _Verification_ > _Results_ tab > **Note** > > Removing an applicant's PII is permanent. You cannot undo this action. > Any information from the applicant's checks that is not linked to their personal identity is retained for your records. Call the [Anonymize an identity verification](https://api-reference.checkout.com/tag/Identity-Verification/#operation/anonymize_identity_verification) endpoint, and provide the verification ID as the `{identity_verification_id}` path parameter. **Production** `GET` `https://identity-verification.checkout.com/identity-verifications/{identity_verification_id}/anonymize` **Sandbox** `GET` `https://identity-verification.sandbox.checkout.com/identity-verifications/{identity_verification_id}/anonymize` ### Response example ```json { "id": "idv_tkoi5db4hryu5cei5vwoabr7we", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we", "status": "approved", "response_codes": [ { "code": 10000, "summary": "approved" } ], "risk_labels": [ "multiple_faces_detected" ], "declared_data": { "name": "Hannah Bret" }, "documents": [ { "full_name": "Hannah Bret", "birth_date": "1934-10-02", "document_type": "ID", "document_issuing_country": "US", "front_image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/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/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we" }, "applicant": { "href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou" } } } ``` You receive an [Identity verification anonymized](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/identity_verification_anonymized.md) webhook.