--- title: "Create an identity verification" method: POST path: "/identity-verifications" tags: ["Identity Verification"] --- # Create an identity verification `POST /identity-verifications` ## Request - Base URL: `https://identity-verification.checkout.com` - URL: `https://identity-verification.checkout.com/identity-verifications` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `string` scopes: `identity-verification` - API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Beta

Create an [identity verification](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities) 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](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities#Configuration). ## Request body - IdvIdentityVerification - `created_on` string, date-time, required: The date and time when the resource was created, in UTC.
Format – `yyyy-mm-ddThh:mm:ss.sss` - `modified_on` string, date-time, required: The date and time when the resource was modified, in UTC.
Format – `yyyy-mm-ddThh:mm:ss.sss` - `applicant_id` string, required: The applicant's unique identifier. - `user_journey_id` string: Your configuration ID. - `status` 'approved' | 'capture_in_progress' | 'checks_in_progress' | 'created' | 'declined' | 'inconclusive' | 'pending' | 'refused' | 'retry_required', required: The [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes). - `response_codes` IdvResponseCode[], required: One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status. - `code` integer, required: The [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes). - `summary` string, required: The description of the [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes). - `risk_labels` IdvRiskLabel[], required: One or more codes that provide more information about risks associated with the verification. - `verified_identity` IdvVerifiedIdentity: The details of the applicant's verified identity. - `full_name` string, required: The applicant's full name. - `first_names` string: The applicant's first names. - `last_name` string: The applicant's last name. - `last_name_at_birth` string: The applicant's last name at birth. - `birth_date` string, date, required: The applicant's birth date.
Format `YYYY-MM-DD` - `birth_place` string: The applicant's birth place. - `nationality` string, ISO 3166-1 alpha-2: The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR` - `gender` 'M' | 'F': The applicant's gender. - `certifications` IdvCertification[]: The certifications associated with the identity verification. - `type` 'diatf': The certification type. - `data` IdvDiatfCertificationData: The certification data returned for the `diatf` certification type. - `gpg45_profile` 'M1A' | 'M1C' | 'H1A': The GPG 45 identity profile the verification meets. - `level_of_confidence` 'medium' | 'high': The level of confidence in the verified identity. - `right_to_work` string: The outcome of the applicant's right to work check. - `verification_policy_version` string: The version of the verification policy applied. Only returned for certified verifications. - `declared_data` IdvIdentityDeclaredData, required: The personal details provided by the applicant. - `name` string, required: The applicant's name. - `birth_date` string, date: The applicant's birth date.
Format – `YYYY-MM-DD` - `phone_number` IdvPhoneNumber: The applicant's mobile phone number, if sharing the attempt URL via SMS. - `country_code` string, required: The international [phone country code](https://www.checkout.com/docs/resources/codes/country-codes). - `number` string, required: The applicant's mobile number, without the country code. - `email` string, email, nullable: The applicant's email address. - `address` IdvAddress: The applicant's address. - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address. - `city` string: The city or town. - `state` string: The state, county, or province. - `zip` string: The postal or ZIP code. - `country` string: The two-letter ISO country code of the address. - `documents` IdvDocument[]: The details of the applicant's identity documents. - `full_name` string, required: The applicant's full name. - `first_names` string: The applicant's first names. - `last_name` string: The applicant's last name. - `last_name_at_birth` string: The applicant's last name at birth. - `birth_date` string, date, required: The applicant's birth date.
Format `YYYY-MM-DD` - `birth_place` string: The applicant's birth place. - `nationality` string, ISO 3166-1 alpha-2: The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR` - `gender` 'M' | 'F': The applicant's gender. - `personal_number` string: The applicant's personal number. This depends on the document type. - `tax_identification_number` string: The tax identification number (TIN) extracted from the document. - `document_type` 'Driving licence' | 'ID' | 'Other' | 'Passport' | 'Residence Permit' | 'Travel Document' | 'Visa', required: The type of identity document. - `document_issuing_country` string, ISO 3166-1 alpha-2, required: The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR` - `document_number` string: The document number extracted from the document. - `document_expiry_date` string, date: The document expiry date extracted from the document. - `document_issue_date` string, date: The document issue date extracted from the document. - `document_issue_place` string: The document's place of issue extracted from the document. - `document_mrz` string: The machine-readable zone (MRZ) data extracted from the document. - `address` string: The address extracted from the document. - `permit_obtaining_date` string, date: The date the residence permit was obtained, extracted from the document. - `permit_expiry_date` string, date: The residence permit expiry date extracted from the document. - `permit_type_detailed` string: The detailed residence permit type extracted from the document. - `permit_type_remarks` string: The residence permit remarks extracted from the document. - `front_image_signed_url` string, uri, required: The pre-signed URL to the captured image of the document. - `back_image_signed_url` string, uri: The pre-signed URL to the captured image of the document. - `signature_image_signed_url` string, uri: The pre-signed URL to the captured image of the document. - `face` IdvFace: The details of the image of the applicant's face extracted from the video. - `image_signed_url` string, uri, required: The pre-signed URL to the captured image of the document. - `_links` IdvIdentityVerificationLinks, required: The details of links related to the resource. - `self` IdvHalLink, required: The URL to the applicant profile resource. - `href` string, uri, required - `applicant` IdvHalLink, required: The URL to the applicant profile resource. - `href` string, uri, required - `id` string, required: The identity verification's unique identifier. ## Response `201` Identity verification created successfully - IdvIdentityVerificationOutput - `created_on` string, date-time, required: The date and time when the resource was created, in UTC.
Format – `yyyy-mm-ddThh:mm:ss.sss` - `modified_on` string, date-time, required: The date and time when the resource was modified, in UTC.
Format – `yyyy-mm-ddThh:mm:ss.sss` - `applicant_id` string, required: The applicant's unique identifier. - `user_journey_id` string: Your configuration ID. - `status` 'approved' | 'capture_in_progress' | 'checks_in_progress' | 'created' | 'declined' | 'inconclusive' | 'pending' | 'refused' | 'retry_required', required: The [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes). - `declared_data` IdvIdentityDeclaredData, required: The personal details provided by the applicant. - `name` string, required: The applicant's name. - `birth_date` string, date: The applicant's birth date.
Format – `YYYY-MM-DD` - `phone_number` IdvPhoneNumber: The applicant's mobile phone number, if sharing the attempt URL via SMS. - `country_code` string, required: The international [phone country code](https://www.checkout.com/docs/resources/codes/country-codes). - `number` string, required: The applicant's mobile number, without the country code. - `email` string, email, nullable: The applicant's email address. - `address` IdvAddress: The applicant's address. - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address. - `city` string: The city or town. - `state` string: The state, county, or province. - `zip` string: The postal or ZIP code. - `country` string: The two-letter ISO country code of the address. - `documents` IdvDocument[]: The details of the applicant's identity documents. - `full_name` string, required: The applicant's full name. - `first_names` string: The applicant's first names. - `last_name` string: The applicant's last name. - `last_name_at_birth` string: The applicant's last name at birth. - `birth_date` string, date, required: The applicant's birth date.
Format `YYYY-MM-DD` - `birth_place` string: The applicant's birth place. - `nationality` string, ISO 3166-1 alpha-2: The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR` - `gender` 'M' | 'F': The applicant's gender. - `personal_number` string: The applicant's personal number. This depends on the document type. - `tax_identification_number` string: The tax identification number (TIN) extracted from the document. - `document_type` 'Driving licence' | 'ID' | 'Other' | 'Passport' | 'Residence Permit' | 'Travel Document' | 'Visa', required: The type of identity document. - `document_issuing_country` string, ISO 3166-1 alpha-2, required: The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR` - `document_number` string: The document number extracted from the document. - `document_expiry_date` string, date: The document expiry date extracted from the document. - `document_issue_date` string, date: The document issue date extracted from the document. - `document_issue_place` string: The document's place of issue extracted from the document. - `document_mrz` string: The machine-readable zone (MRZ) data extracted from the document. - `address` string: The address extracted from the document. - `permit_obtaining_date` string, date: The date the residence permit was obtained, extracted from the document. - `permit_expiry_date` string, date: The residence permit expiry date extracted from the document. - `permit_type_detailed` string: The detailed residence permit type extracted from the document. - `permit_type_remarks` string: The residence permit remarks extracted from the document. - `front_image_signed_url` string, uri, required: The pre-signed URL to the captured image of the document. - `back_image_signed_url` string, uri: The pre-signed URL to the captured image of the document. - `signature_image_signed_url` string, uri: The pre-signed URL to the captured image of the document. - `face` IdvFace: The details of the image of the applicant's face extracted from the video. - `image_signed_url` string, uri, required: The pre-signed URL to the captured image of the document. - `response_codes` IdvResponseCode[], required: One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status. - `code` integer, required: The [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes). - `summary` string, required: The description of the [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes). - `risk_labels` IdvRiskLabel[], required: One or more codes that provide more information about risks associated with the verification. - `verified_identity` IdvVerifiedIdentity: The details of the applicant's verified identity. - `full_name` string, required: The applicant's full name. - `first_names` string: The applicant's first names. - `last_name` string: The applicant's last name. - `last_name_at_birth` string: The applicant's last name at birth. - `birth_date` string, date, required: The applicant's birth date.
Format `YYYY-MM-DD` - `birth_place` string: The applicant's birth place. - `nationality` string, ISO 3166-1 alpha-2: The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR` - `gender` 'M' | 'F': The applicant's gender. - `certifications` IdvCertification[]: The certifications associated with the identity verification. - `type` 'diatf': The certification type. - `data` IdvDiatfCertificationData: The certification data returned for the `diatf` certification type. - `gpg45_profile` 'M1A' | 'M1C' | 'H1A': The GPG 45 identity profile the verification meets. - `level_of_confidence` 'medium' | 'high': The level of confidence in the verified identity. - `right_to_work` string: The outcome of the applicant's right to work check. - `verification_policy_version` string: The version of the verification policy applied. Only returned for certified verifications. - `_links` IdvIdentityVerificationLinks, required: The details of links related to the resource. - `self` IdvHalLink, required: The URL to the applicant profile resource. - `href` string, uri, required - `applicant` IdvHalLink, required: The URL to the applicant profile resource. - `href` string, uri, required - `id` string, required: The identity verification's unique identifier. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `422`: Unprocessable Content - `500`: Internal Server Error - `503`: Service Unavailable --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)