Identity Verification

Identity Verification Operations

post/create-and-open-idv
post/identity-verifications
get/identity-verifications/{identity_verification_id}
post/identity-verifications/{identity_verification_id}/anonymize
post/identity-verifications/{identity_verification_id}/attempts
get/identity-verifications/{identity_verification_id}/attempts
get/identity-verifications/{identity_verification_id}/attempts/{attempt_id}
get/identity-verifications/{identity_verification_id}/attempts/{attempt_id}/assets
get/identity-verifications/{identity_verification_id}/pdf-report

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.

Body·

required

application/json

Type: object
- declared_data
  Type: object ·
  required
  
  The personal details provided by the applicant.
- redirect_url
  Type: string Format: uri
  required
  
  The URL to redirect the applicant to after the attempt.
- user_journey_id
  Type: string · Pattern: ^usj_[a-z2-7]{26}$
  
  Your configuration ID.
- applicant_id
  Type: string · Pattern: ^aplt_\w+$
  
  The applicant's unique identifier.

Responses

application/json

post/create-and-open-idv

curl https://identity-verification.checkout.com/create-and-open-idv \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "declared_data": {
    "name": "Hannah Bret"
  },
  "redirect_url": "https://myweb.site?query-param=hello"
}'

Show Schema

{
  "id": "idv_tkoi5db4hryu5cei5vwoabr7we",
  "created_on": {},
  "modified_on": {},
  "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
  "status": "pending",
  "response_codes": [],
  "risk_labels": [],
  "certifications": [],
  "declared_data": {
    "name": "Hannah Bret",
    "birth_date": "1994-10-15"
  },
  "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/"
    }
  }
}

Identity verification and attempt created successfully

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.

Body·

required

application/json

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

Responses

application/json
application/json
401

Unauthorized
application/json
500

Internal Server Error
503

Service Unavailable

post/identity-verifications

curl https://identity-verification.checkout.com/identity-verifications \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
  "declared_data": {
    "name": "Hannah Bret"
  }
}'

Show Schema

{
  "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": [],
  "certifications": [],
  "declared_data": {
    "name": "Hannah Bret",
    "birth_date": "1994-10-15"
  },
  "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"
    }
  }
}

Identity verification created successfully

Get an identity verification

Beta

Get the details of an existing identity verification.

Path Parameters

identity_verification_id
Type: string · Pattern: ^idv_\w+$
read-only
required

The identity verification's unique identifier.

Responses

application/json
401

Unauthorized
500

Internal Server Error
503

Service Unavailable

get/identity-verifications/{identity_verification_id}

Shell Curl

curl https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "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"
  },
  "verification_policy_version": "2.1",
  "certifications": [
    {
      "type": "diatf",
      "data": {
        "gpg45_profile": "M1A",
        "level_of_confidence": "high",
        "right_to_work": "GRANTED"
      }
    }
  ],
  "declared_data": {
    "name": "Hannah Bret",
    "birth_date": "1934-10-02",
    "email": "hannah.bret@example.com",
    "phone_number": {
      "country_code": "+1",
      "number": "5555550102"
    },
    "address": {
      "address_line1": "123 Main Street",
      "address_line2": "Apt 4B",
      "city": "London",
      "state": "Greater London",
      "zip": "SW1A 1AA",
      "country": "GB"
    }
  },
  "documents": [
    {
      "full_name": "Hannah Bret",
      "birth_date": "1934-10-02",
      "document_type": "ID",
      "document_issuing_country": "US",
      "address": "123 Main Street, London, SW1A 1AA",
      "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"
    }
  }
}

Identity verification retrieved successfully

Anonymize an identity verification

Beta

Remove the personal data in an identity verification.

Path Parameters

identity_verification_id
Type: string · Pattern: ^idv_\w+$
read-only
required

The identity verification's unique identifier.

Responses

application/json
401

Unauthorized
404

Not Found
application/json
500

Internal Server Error
503

Service Unavailable

post/identity-verifications/{identity_verification_id}/anonymize

Shell Curl

curl https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/anonymize \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "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"
  ],
  "certifications": [],
  "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"
    }
  }
}

Personal data removed successfully

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.

Path Parameters

identity_verification_id
Type: string · Pattern: ^idv_\w+$
read-only
required

The identity verification's unique identifier.

Body·

application/json

redirect_url
Type: string Format: uri
required

The URL to redirect the applicant to after the attempt.
phone_number
Type: object ·

The applicant's mobile phone number, if sharing the attempt URL via SMS.
client_information
Type: object ·

The applicant's details.

Responses

application/json
404

Not Found
409

Conflict
500

Internal Server Error

post/identity-verifications/{identity_verification_id}/attempts

curl https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "redirect_url": "https://myweb.site?query-param=hello"
}'

Show Schema

{
  "id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
  "created_on": {},
  "modified_on": {},
  "phone_number": {
    "country_code": "+1",
    "number": "5555550102"
  },
  "client_information": {
    "pre_selected_residence_country": "FR",
    "pre_selected_document_issuing_country": "FR",
    "pre_selected_document_type": "ID",
    "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"
    }
  }
}

Identity verification attempt created successfully

Get identity verification attempts

Beta

Get all the attempts for a specific identity verification.

Path Parameters

identity_verification_id
Type: string · Pattern: ^idv_\w+$
read-only
required

The identity verification's unique identifier.

Query Parameters

skip
Type: integer

The number of attempts to skip.
limit
Type: integer

The maximum number of attempts to return.

Responses

application/json
404

Not Found
500

Internal Server Error

get/identity-verifications/{identity_verification_id}/attempts

Shell Curl

curl https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "total_count": 2,
  "skip": 10,
  "limit": 10,
  "data": [
    {
      "id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
      "created_on": {},
      "modified_on": {},
      "status": "completed",
      "response_codes": [],
      "phone_number": {
        "country_code": "+1",
        "number": "5555550102"
      },
      "client_information": {
        "pre_selected_residence_country": "FR",
        "pre_selected_document_issuing_country": "FR",
        "pre_selected_document_type": "Passport",
        "pre_selected_language": "en-US"
      },
      "applicant_session_information": {
        "ip_address": "123.123.123.01",
        "number_of_sessions": 3,
        "user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
        "initial_device": "mobile",
        "selected_documents": [
          {
            "country": "FR",
            "document_type": "Passport"
          }
        ]
      },
      "redirect_url": "https://myweb.site?query-param=hello",
      "_links": {
        "self": {
          "href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ"
        },
        "verification_url": {
          "href": "https://idv.checkout.com/4hryu5cei5/"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts?skip=10&limit=10"
    },
    "next": {
      "href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts?skip=20&limit=10"
    },
    "previous": {
      "href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts?skip=0&limit=10"
    }
  }
}

Identity verification attempts retrieved successfully

Get an identity verification attempt

Beta

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

Path Parameters

identity_verification_id
Type: string · Pattern: ^idv_\w+$
read-only
required

The identity verification's unique identifier.
attempt_id
Type: string · Pattern: ^iatp_\w+$
read-only
required

The attempt's unique identifier.

The unique identifier for the attempt.

Responses

application/json
404

Not Found
500

Internal Server Error

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

Shell Curl

curl https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabraio \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
  "created_on": {},
  "modified_on": {},
  "redirect_url": "https://myweb.site?query-param=hello",
  "status": "capture_in_progress",
  "phone_number": {
    "country_code": "+1",
    "number": "5555550102"
  },
  "client_information": {
    "pre_selected_residence_country": "FR",
    "pre_selected_document_issuing_country": "FR",
    "pre_selected_document_type": "Passport",
    "pre_selected_language": "en-US"
  },
  "applicant_session_information": {
    "ip_address": "123.123.123.01",
    "number_of_sessions": 3,
    "user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
    "initial_device": "mobile",
    "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/"
    }
  }
}

Identity verification attempt retrieved successfully

Get identity verification attempt assets

Beta

Get the assets (face images, videos, and document images) captured during an identity verification attempt.

Videos are not exposed by default. Contact your account manager to enable this feature.

Results are paginated. Use the skip and limit query parameters to navigate through pages.

Path Parameters

identity_verification_id
Type: string · Pattern: ^idv_\w+$
read-only
required

The identity verification's unique identifier.
attempt_id
Type: string · Pattern: ^iatp_\w+$
read-only
required

The attempt's unique identifier.

The unique identifier for the attempt.

Query Parameters

skip
Type: integer

The number of assets to skip.
limit
Type: integer

The maximum number of assets to return.

Responses

application/json
404

Not Found
500

Internal Server Error

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

Shell Curl

curl https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabraio/assets \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "total_count": 4,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "type": "face_image",
      "_links": {
        "asset_url": {
          "href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/face_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
        }
      }
    },
    {
      "type": "face_video",
      "_links": {
        "asset_url": {
          "href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/face_video.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
        }
      }
    },
    {
      "type": "document_front_image",
      "_links": {
        "asset_url": {
          "href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/document_front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
        }
      }
    },
    {
      "type": "document_back_image",
      "_links": {
        "asset_url": {
          "href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/document_back.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ/assets"
    },
    "next": {
      "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ/assets?..."
    },
    "previous": {
      "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ/assets?..."
    }
  }
}

Identity verification attempt assets retrieved successfully

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.

Path Parameters

identity_verification_id
Type: string · Pattern: ^idv_\w+$
read-only
required

The identity verification's unique identifier.

Responses

application/json
404

Not Found
500

Internal Server Error
503

Service Unavailable

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

Shell Curl

curl https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/pdf-report \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "pdf_report": "https://www.example.com/reports/idv_tkoi5db4hryu5cei5vwoabr7we.pdf"
}

Identity verification report retrieved successfully