Identity Verification

Create an identity verification and attempt

Beta

Create an identity verification and an initial attempt.

If successful, you receive a 201 Created response and the identity verification resource, which contains the attempt URL.

Ensure you use your identity verification configuration ID.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

Request Body schema: application/json
required

required	object (IdvDeclaredData) The personal details provided by the applicant.
redirect_url required	string <uri> The URL to redirect the applicant to after the attempt.
user_journey_id	string^usj_[a-z2-7]{26}$ Your configuration ID.
applicant_id	string^aplt_\w+$ The applicant's unique identifier.

Responses

201

Identity verification and attempt created successfully

post/create-and-open-idv

Request samples

Payload
curl
Java
C#
Python

application/json

{"declared_data": {"name": "Hannah Bret"
},
"redirect_url": "https://myweb.site?query-param=hello"
}

Response samples

application/json

{"id": "idv_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": "pending",
"response_codes": [ ],
"risk_labels": [ ],
"declared_data": {"name": "Hannah Bret"
},
"documents": [ ],
"redirect_url": "https://myweb.site?query-param=hello",
"_links": {"self": {"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
},
"verification_url": {"href": "https://idv.checkout.com/4hryu5cei5/"
}
}
}

Create an identity verification

Beta

Create an identity verification linked to an applicant.

If successful, you receive a 201 Created response with the identity verification resource.

Ensure you use your identity verification configuration ID.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

Request Body schema: application/json
required

applicant_id required	string^aplt_\w+$ The applicant's unique identifier.
required	object (IdvDeclaredData) The personal details provided by the applicant.
user_journey_id	string^usj_[a-z2-7]{26}$ Your configuration ID.

Responses

201

Identity verification created successfully

400

Bad Request

401

Unauthorized

422

Unprocessable Content

500

Internal Server Error

503

Service Unavailable

post/identity-verifications

Request samples

Payload
curl
Java
C#
Python

application/json

{"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {"name": "Hannah Bret"
},
"redirect_url": "https://example.com?query-param=hello"
}

Response samples

application/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": "pending",
"response_codes": [ ],
"risk_labels": [ ],
"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_lkoi5db4hryu5cei5vwoabqere"
}
}
}

Get an identity verification

Beta

Get the details of an existing identity verification.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

identity_verification_id

required

string (IdvIdentityVerificationId) ^idv_\w+$

The identity verification's unique identifier.

Example: idv_tkoi5db4hryu5cei5vwoabr7we

Responses

200

Identity verification retrieved successfully

401

Unauthorized

500

Internal Server Error

503

Service Unavailable

get/identity-verifications/{identity_verification_id}

Request samples

curl
Java
C#
Python

Response samples

application/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"
],
"verified_identity": {"full_name": "Hannah Bret",
"birth_date": "1934-10-02"
},
"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"
}
],
"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"
},
"_links": {"self": {"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
}
}
}

Anonymize an identity verification

Beta

Remove the personal data in an identity verification.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

identity_verification_id

required

string (IdvIdentityVerificationId) ^idv_\w+$

The identity verification's unique identifier.

Example: idv_tkoi5db4hryu5cei5vwoabr7we

Responses

200

Personal data removed successfully

401

Unauthorized

404

Not Found

422

Unprocessable Content

500

Internal Server Error

503

Service Unavailable

post/identity-verifications/{identity_verification_id}/anonymize

Request samples

curl
Java
C#
Python

Response samples

application/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"
}
}
}

Create an identity verification attempt

Beta

Create an identity verification attempt.

If you've already created an attempt for this verification, the verification status must be one of the following:

created
pending
capture_in_progress
retry_required

If you create a new attempt while the status is any other value, you receive a 409 Conflict response.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

identity_verification_id

required

string (IdvIdentityVerificationId) ^idv_\w+$

The identity verification's unique identifier.

Example: idv_tkoi5db4hryu5cei5vwoabr7we

Request Body schema: application/json

redirect_url required	string <uri> The URL to redirect the applicant to after the attempt.
	object (ClientInformation) The applicant's details.

Responses

201

Identity verification attempt created successfully

404

Not Found

409

Conflict

500

Internal Server Error

post/identity-verifications/{identity_verification_id}/attempts

Request samples

Payload
curl
Java
C#
Python

application/json

{"redirect_url": "https://myweb.site?query-param=hello"
}

Response samples

application/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"
},
"applicant_session_information": {"ip_address": "123.123.123.01"
},
"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"
}
}
}

Get identity verification attempts

Beta

Get all the attempts for a specific identity verification.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

identity_verification_id

required

string (IdvIdentityVerificationId) ^idv_\w+$

The identity verification's unique identifier.

Example: idv_tkoi5db4hryu5cei5vwoabr7we

Responses

200

Identity verification attempts retrieved successfully

404

Not Found

500

Internal Server Error

get/identity-verifications/{identity_verification_id}/attempts

Request samples

curl
Java
C#
Python

Response samples

application/json

{"total_count": 2,
"skip": 10,
"limit": 10,
"data": [{"id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "completed",
"response_codes": [ ],
"applicant_session_information": {"ip_address": "123.123.123.01"
},
"redirect_url": "https://myweb.site?query-param=hello",
"_links": {"verification_url": {"href": "https://idv.checkout.com/4hryu5cei5/"
}
}
}
],
"_links": {"self": {"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts"
},
"next": {"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts?..."
},
"previous": {"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts?..."
}
}
}

Get an identity verification attempt

Beta

Get the details of a specific attempt for an identity verification.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

identity_verification_id required	string (IdvIdentityVerificationId) ^idv_\w+$ The identity verification's unique identifier. Example: idv_tkoi5db4hryu5cei5vwoabr7we
attempt_id required	string (IdvAttemptId) ^iatp_\w+$ The attempt's unique identifier. Example: iatp_tkoi5db4hryu5cei5vwoabraio

Responses

200

Identity verification attempt retrieved successfully

404

Not Found

500

Internal Server Error

get/identity-verifications/{identity_verification_id}/attempts/{attempt_id}

Request samples

curl
Java
C#
Python

Response samples

application/json

{"id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"redirect_url": "https://myweb.site?query-param=hello",
"status": "capture_in_progress",
"client_information": {"pre_selected_residence_country": "FR",
"pre_selected_language": "en-US"
},
"applicant_session_information": {"ip_address": "123.123.123.01",
"selected_documents": [{"country": "FR",
"document_type": "Passport"
}
]
},
"response_codes": [ ],
"_links": {"self": {"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabraio"
},
"verification_url": {"href": "https://idv.checkout.com/4hryu5cei5/"
}
}
}

Get identity verification report

Beta

Get the report with the full details of an identity verification in PDF format.

The report is only available when the verification status is approved or declined, and you've received an Identity verification report created webhook.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

identity_verification_id

required

string (IdvIdentityVerificationId) ^idv_\w+$

The identity verification's unique identifier.

Example: idv_tkoi5db4hryu5cei5vwoabr7we

Responses

200

Identity verification report retrieved successfully

404

Not Found

500

Internal Server Error

503

Service Unavailable

get/identity-verifications/{identity_verification_id}/pdf-report

Request samples

curl
Java
C#
Python

Response samples

application/json

{"pdf_report": "https://www.example.com/pdf",
"signed_url": "https://www.example.com/signed/pdf"
}

➔ Next to AML Screening

Identity Verification

Create an identity verification and attempt

Request Body schema: application/jsonrequired

Create an identity verification

Request Body schema: application/jsonrequired

Get an identity verification

path Parameters

Anonymize an identity verification

path Parameters

Create an identity verification attempt

path Parameters

Request Body schema: application/json

Get identity verification attempts

path Parameters

Get an identity verification attempt

path Parameters

Get identity verification report

path Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required