Create a VerificationSession

Creates a VerificationSession object.

After the VerificationSession is created, display a verification modal using the session client_secret or send your users to the session’s url.

If your API key is in test mode, verification checks won’t actually process, though everything else will occur as if in live mode.

Related guide: Verify your users’ identity documents

Returns

Returns the created VerificationSession object

Parameters

• client_reference_id (string, optional) A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.

• metadata (object, optional) Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

• options (object, optional) A set of options for the session’s verification checks.

  • options.document (object, optional) Options that apply to the document check.

    • options.document.allowed_types (array of enums, optional) Array of strings of allowed identity document types. If the provided identity document isn’t one of the allowed types, the verification check will fail with a document_type_not_allowed error code. Possible enum values:

      • driving_license Drivers license document type.

      • id_card ID card document type.

      • passport Passport document type.

    • options.document.require_id_number (boolean, optional) Collect an ID number and perform an ID number check with the document’s extracted name and date of birth.

    • options.document.require_live_capture (boolean, optional) Disable image uploads, identity document images have to be captured using the device’s camera.

    • options.document.require_matching_selfie (boolean, optional) Capture a face image and perform a selfie check comparing a photo ID and a picture of your user’s face. Learn more.

• provided_details (object, optional) Details provided about the user being verified. These details might be shown to the user.

  • provided_details.email (string, optional) Email of user being verified

    The maximum length is 800 characters.

  • provided_details.phone (string, optional) Phone number of user being verified

• related_customer (string, optional) Customer ID

• related_customer_account (string, optional) The ID of the Account representing a customer.

• related_person (object, optional) Tokens referencing a Person resource and its associated account.

  • related_person.account (string, required) A token representing a connected account. If provided, the person parameter is also required and must be associated with the account.

  • related_person.person (string, required) A token referencing a Person resource that this verification is being used to verify.

• return_url (string, optional) The URL that the user will be redirected to upon completing the verification flow.

• type (enum, optional) The type of verification check to be performed. You must provide a type if not passing verification_flow. Possible enum values:

  • document Document check.

  • id_number ID number check.

• verification_flow (string, optional) The ID of a verification flow from the Dashboard. See https://docs.stripe.com/identity/verification-flows.

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "<<YOUR_SECRET_KEY>>" \
  -d type=document

Response

{
  "id": "vs_1NuN4zLkdIwHu7ixleE6HvkI",
  "object": "identity.verification_session",
  "client_secret": "...",
  "created": 1695680197,
  "last_error": null,
  "last_verification_report": null,
  "livemode": false,
  "metadata": {},
  "options": {},
  "redaction": null,
  "status": "requires_input",
  "type": "document",
  "url": "..."
}