Verify identities using the API
Beta

Last updated: January 21, 2026

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.

Set up an authentication mechanism for your API requests, using OAuth 2.0 or API keys.
Integrate Identity Verification in your web app or mobile app.
Handle statuses, attempts, and response codes.
Configure your webhook server and subscribe to Identity Verification webhooks.
Create an applicant profile.

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

Create an identity verification linked to the applicant's profile.
Create an attempt.
Redirect the applicant to the attempt URL.
View the identity verification to see the result.
Download the identity verification report.
If requested, you can remove the applicant's personal details from the identity verification.

Information

To test your integration, see Identity Verification testing.

To create an identity verification, you must have already created a profile for the applicant. You need the applicant ID either from the Dashboard or from the id field in the Create an applicant response.

Call the Create an 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.

post

https://identity-verification.checkout.com/identity-verifications


1{
2  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
3  "declared_data": {
4    "name": "Hannah Bret"
5  },
6  "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we"
7}


1{
2  "id": "idv_tkoi5db4hryu5cei5vwoabr7we",
3  "created_on": "2025-07-21T17:32:28Z",
4  "modified_on": "2025-07-21T17:40:32Z",
5  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
6  "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
7  "status": "created",
8  "response_codes": [],
9  "declared_data": {
10    "name": "Hannah Bret",
11    "birth_date": "1994-10-15"
12  },
13  "documents": [],
14  "_links": {
15    "self": {
16      "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
17    },
18    "applicant": {
19      "href": "https://identity-verification.checkout.com/applicants/aplt_lkoi5db4hryu5cei5vwoabqere"
20    }
21  }
22}

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 webhook.

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 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.

post

https://identity-verification.checkout.com/identity-verifications/{identity_verification_id}/attempts


1{
2  "redirect_url": "https://myweb.site?query-param=hello",
3  "client_information": {
4    "pre_selected_residence_country": "FR",
5    "pre_selected_language": "en-US"
6  }
7}


1{
2  "id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
3  "created_on": "2025-07-21T17:32:28Z",
4  "modified_on": "2025-07-21T17:40:32Z",
5  "client_information": {
6    "pre_selected_residence_country": "FR",
7    "pre_selected_language": "en-US"
8  },
9  "redirect_url": "https://myweb.site?query-param=hello",
10  "status": "pending_redirection",
11  "response_codes": [ ],
12  "_links": {
13    "verification_url": {
14      "href": "https://idv.checkout.com/4hryu5cei5/"
15    },
16    "self": {
17      "href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_01j58p8rw1hvterhqt66xn6js2/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ"
18    }
19  }
20}

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 webhook.

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.

The following table describes the process of a successful attempt:

Scenario Description

Scenario	Description
Applicant starts the attempt	The verification and attempt statuses change to `capture_in_progress`. You receive an Identity verification started webhook. When successfully completed, the attempt status changes to `completed`. You receive an Identity verification capture completed 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 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 webhook.

Applicant starts the attempt

The verification and attempt statuses change to capture_in_progress.

You receive an Identity verification started webhook.

When successfully completed, the attempt status changes to completed.

You receive an Identity verification capture completed 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 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 webhook.

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 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 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 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 webhook. When you create a new attempt, the status of the previous attempt changes to `terminated`. You receive an Identity verification closed webhook, followed by an Identity verification reset 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 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.

You can retrieve identity verification attempts using the following endpoints:

Get identity verification attempts – View all attempts for a verification.
Get an identity verification attempt – View the details of a specific attempt.

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 endpoint, and provide the verification ID as the {identity_verification_id} path parameter.

get

https://identity-verification.checkout.com/identity-verifications/{identity_verification_id}


1{
2  "id": "idv_tkoi5db4hryu5cei5vwoabr7we",
3  "created_on": "2025-07-21T17:32:28Z",
4  "modified_on": "2025-07-21T17:40:32Z",
5  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
6  "user_journey_id": "usj_5hxpdwegjcbujpth3wdo55d3vm",
7  "status": "approved",
8  "response_codes": [
9    {
10      "code": 10000,
11      "summary": "approved"
12    }
13  ],
14  "verified_identity": {
15    "full_name": "Hannah Bret",
16    "birth_date": "1994-10-15"
17  },
18  "declared_data": {
19    "name": "Hannah Bret",
20    "birth_date": "1994-10-15"
21  },
22  "documents": [
23    {
24      "full_name": "Hannah Bret",
25      "birth_date": "1994-10-15",
26      "document_type": "ID",
27      "document_issuing_country": "US",
28      "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"
29    }
30  ],
31  "face": {
32    "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"
33  },
34  "phone_number": {
35    "country_code": "+1",
36    "number": "2068133616"
37  },
38  "redirect_url": "https://example.com?query-param=hello",
39  "_links": {
40    "self": {
41      "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
42    },
43    "verification_url": {
44      "href": "https://idv.checkout.com/4hryu5cei5/"
45    }
46  }
47}

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

A detailed report for the identity verification is provided in PDF format. When the report is ready, you receive an Identity verification report created webhook.

Call the Get identity verification report endpoint, and provide the verification ID as the {identity_verification_id} path parameter.

get

https://identity-verification.checkout.com/identity-verifications/{identity_verification_id}/pdf-report


1{
2  "value": {
3    "pdf_report": "https://www.example.com/pdf"
4  }
5}

The response returns a URL where you can download the report.

Information

Download a sample report.

If using Safari, hold down the Option key when selecting the link to download the file.

If the identity verification is later audited and the status updated, you receive an Identity verification audit completed webhook.

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 endpoint, and provide the verification ID as the {identity_verification_id} path parameter.

get

https://identity-verification.checkout.com/identity-verifications/{identity_verification_id}/anonymize


1{
2  "id": "idv_tkoi5db4hryu5cei5vwoabr7we",
3  "created_on": "2025-07-21T17:32:28Z",
4  "modified_on": "2025-07-21T17:40:32Z",
5  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
6  "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
7  "status": "approved",
8  "response_codes": [
9    {
10      "code": 10000,
11      "summary": "approved"
12    }
13  ],
14  "risk_labels": [
15    "multiple_faces_detected"
16  ],
17  "declared_data": {
18    "name": "Hannah Bret"
19  },
20  "documents": [
21    {
22      "full_name": "Hannah Bret",
23      "birth_date": "1934-10-02",
24      "document_type": "ID",
25      "document_issuing_country": "US",
26      "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"
27    }
28  ],
29  "_links": {
30    "self": {
31      "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
32    },
33    "applicant": {
34      "href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
35    }
36  }
37}

You receive an Identity verification anonymized webhook.

Verify identities using the API
Beta

Information

Before you begin

Configuration

How it works

Information

Create a verification

Request example

Response example

Create an attempt

Information

Request example

Response example

Redirect the applicant

Note

Information

View attempts

Retrieve a verification

Response example

Download the report

Response example

Information

Audits

Remove personal details

Note

Response example