---
title: "Create a VerificationSession"
method: POST
path: "/v1/identity/verification_sessions"
---

# Create a VerificationSession

`POST /v1/identity/verification_sessions`

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](/docs/identity/verify-identity-documents)

## Response `200`

Successful response.

- IdentityVerificationSession — A VerificationSession guides you through the process of collecting and verifying the identities of your users. It contains details about the type of verification, such as what [verification check](/docs/identity/verification-checks) to perform. Only create one VerificationSession for each verification in your system. A VerificationSession transitions through [multiple statuses](/docs/identity/how-sessions-work) throughout its lifetime as it progresses through the verification flow. The VerificationSession contains the user's verified data after verification checks are complete. Related guide: [The Verification Sessions API](https://docs.stripe.com/identity/verification-sessions)
  - `client_reference_id` string, nullable — 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.
  - `client_secret` string, nullable — The short-lived client secret used by Stripe.js to [show a verification modal](https://docs.stripe.com/js/identity/modal) inside your app. This client secret expires after 24 hours and can only be used once. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the user. Make sure that you have TLS enabled on any page that includes the client secret. Refer to our docs on [passing the client secret to the frontend](https://docs.stripe.com/identity/verification-sessions#client-secret) to learn more.
  - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
  - `id` string, required — Unique identifier for the object.
  - `last_error` GelatoSessionLastError — Shows last VerificationSession error
    - `code` 'abandoned' | 'consent_declined' | 'country_not_supported' | 'device_not_supported' | 'document_expired' | 'document_type_not_supported' | 'document_unverified_other' | 'email_unverified_other' | 'email_verification_declined' | 'id_number_insufficient_document_data' | 'id_number_mismatch' | 'id_number_unverified_other' | 'phone_unverified_other' | 'phone_verification_declined' | 'selfie_document_missing_photo' | 'selfie_face_mismatch' | 'selfie_manipulated' | 'selfie_unverified_other' | 'under_supported_age', nullable — A short machine-readable string giving the reason for the verification or user-session failure.
    - `reason` string, nullable — A message that explains the reason for verification or user-session failure.
  - `last_verification_report` union — ID of the most recent VerificationReport. [Learn more about accessing detailed verification results.](https://docs.stripe.com/identity/verification-sessions#results)
    - string
    - IdentityVerificationReport — A VerificationReport is the result of an attempt to collect and verify data from a user. The collection of verification checks performed is determined from the `type` and `options` parameters used. You can find the result of each verification check performed in the appropriate sub-resource: `document`, `id_number`, `selfie`. Each VerificationReport contains a copy of any data collected by the user as well as reference IDs which can be used to access collected images through the [FileUpload](https://docs.stripe.com/api/files) API. To configure and create VerificationReports, use the [VerificationSession](https://docs.stripe.com/api/identity/verification_sessions) API. Related guide: [Accessing verification results](https://docs.stripe.com/identity/verification-sessions#results).
      - `client_reference_id` string, nullable — 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.
      - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
      - `document` GelatoDocumentReport — Result from a document check
        - `address` Address
          - `city` string, nullable — City, district, suburb, town, or village.
          - `country` string, nullable — Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
          - `line1` string, nullable — Address line 1, such as the street, PO Box, or company name.
          - `line2` string, nullable — Address line 2, such as the apartment, suite, unit, or building.
          - `postal_code` string, nullable — ZIP or postal code.
          - `state` string, nullable — State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)).
        - `dob` GelatoDataDocumentReportDateOfBirth — Point in Time
          - `day` integer, nullable — Numerical day between 1 and 31.
          - `month` integer, nullable — Numerical month between 1 and 12.
          - `year` integer, nullable — The four-digit year.
        - `error` GelatoDocumentReportError
          - `code` 'document_expired' | 'document_type_not_supported' | 'document_unverified_other', nullable — A short machine-readable string giving the reason for the verification failure.
          - `reason` string, nullable — A human-readable message giving the reason for the failure. These messages can be shown to your users.
        - `expiration_date` GelatoDataDocumentReportExpirationDate — Point in Time
          - `day` integer, nullable — Numerical day between 1 and 31.
          - `month` integer, nullable — Numerical month between 1 and 12.
          - `year` integer, nullable — The four-digit year.
        - `files` string[], nullable — Array of [File](https://docs.stripe.com/api/files) ids containing images for this document.
        - `first_name` string, nullable — First name as it appears in the document.
        - `issued_date` GelatoDataDocumentReportIssuedDate — Point in Time
          - `day` integer, nullable — Numerical day between 1 and 31.
          - `month` integer, nullable — Numerical month between 1 and 12.
          - `year` integer, nullable — The four-digit year.
        - `issuing_country` string, nullable — Issuing country of the document.
        - `last_name` string, nullable — Last name as it appears in the document.
        - `number` string, nullable — Document ID number.
        - `sex` '[redacted]' | 'female' | 'male' | 'unknown', nullable — Sex of the person in the document.
        - `status` 'unverified' | 'verified', required — Status of this `document` check.
        - `type` 'driving_license' | 'id_card' | 'passport', nullable — Type of the document.
        - `unparsed_place_of_birth` string, nullable — Place of birth as it appears in the document.
        - `unparsed_sex` string, nullable — Sex as it appears in the document.
      - `email` GelatoEmailReport — Result from a email check
        - `email` string, nullable — Email to be verified.
        - `error` GelatoEmailReportError
          - `code` 'email_unverified_other' | 'email_verification_declined', nullable — A short machine-readable string giving the reason for the verification failure.
          - `reason` string, nullable — A human-readable message giving the reason for the failure. These messages can be shown to your users.
        - `status` 'unverified' | 'verified', required — Status of this `email` check.
      - `id` string, required — Unique identifier for the object.
      - `id_number` GelatoIdNumberReport — Result from an id_number check
        - `dob` GelatoDataIdNumberReportDate — Point in Time
          - `day` integer, nullable — Numerical day between 1 and 31.
          - `month` integer, nullable — Numerical month between 1 and 12.
          - `year` integer, nullable — The four-digit year.
        - `error` GelatoIdNumberReportError
          - `code` 'id_number_insufficient_document_data' | 'id_number_mismatch' | 'id_number_unverified_other', nullable — A short machine-readable string giving the reason for the verification failure.
          - `reason` string, nullable — A human-readable message giving the reason for the failure. These messages can be shown to your users.
        - `first_name` string, nullable — First name.
        - `id_number` string, nullable — ID number. When `id_number_type` is `us_ssn`, only the last 4 digits are present.
        - `id_number_type` 'br_cpf' | 'sg_nric' | 'us_ssn', nullable — Type of ID number.
        - `last_name` string, nullable — Last name.
        - `status` 'unverified' | 'verified', required — Status of this `id_number` check.
      - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
      - `object` 'identity.verification_report', required — String representing the object's type. Objects of the same type share the same value.
      - `options` GelatoVerificationReportOptions
        - `document` GelatoReportDocumentOptions
          - `allowed_types` string[] — 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.
          - `require_id_number` boolean — Collect an ID number and perform an [ID number check](https://docs.stripe.com/identity/verification-checks?type=id-number) with the document’s extracted name and date of birth.
          - `require_live_capture` boolean — Disable image uploads, identity document images have to be captured using the device’s camera.
          - `require_matching_selfie` boolean — Capture a face image and perform a [selfie check](https://docs.stripe.com/identity/verification-checks?type=selfie) comparing a photo ID and a picture of your user’s face. [Learn more](https://docs.stripe.com/identity/selfie).
        - `id_number` GelatoReportIdNumberOptions
      - `phone` GelatoPhoneReport — Result from a phone check
        - `error` GelatoPhoneReportError
          - `code` 'phone_unverified_other' | 'phone_verification_declined', nullable — A short machine-readable string giving the reason for the verification failure.
          - `reason` string, nullable — A human-readable message giving the reason for the failure. These messages can be shown to your users.
        - `phone` string, nullable — Phone to be verified.
        - `status` 'unverified' | 'verified', required — Status of this `phone` check.
      - `selfie` GelatoSelfieReport — Result from a selfie check
        - `document` string, nullable — ID of the [File](https://docs.stripe.com/api/files) holding the image of the identity document used in this check.
        - `error` GelatoSelfieReportError
          - `code` 'selfie_document_missing_photo' | 'selfie_face_mismatch' | 'selfie_manipulated' | 'selfie_unverified_other', nullable — A short machine-readable string giving the reason for the verification failure.
          - `reason` string, nullable — A human-readable message giving the reason for the failure. These messages can be shown to your users.
        - `selfie` string, nullable — ID of the [File](https://docs.stripe.com/api/files) holding the image of the selfie used in this check.
        - `status` 'unverified' | 'verified', required — Status of this `selfie` check.
      - `type` 'document' | 'id_number' | 'verification_flow', required — Type of report.
      - `verification_flow` string — The configuration token of a verification flow from the dashboard.
      - `verification_session` string, nullable — ID of the VerificationSession that created this report.
  - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
  - `metadata` object, required — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  - `object` 'identity.verification_session', required — String representing the object's type. Objects of the same type share the same value.
  - `options` GelatoVerificationSessionOptions
    - `document` GelatoSessionDocumentOptions
      - `allowed_types` string[] — 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.
      - `require_id_number` boolean — Collect an ID number and perform an [ID number check](https://docs.stripe.com/identity/verification-checks?type=id-number) with the document’s extracted name and date of birth.
      - `require_live_capture` boolean — Disable image uploads, identity document images have to be captured using the device’s camera.
      - `require_matching_selfie` boolean — Capture a face image and perform a [selfie check](https://docs.stripe.com/identity/verification-checks?type=selfie) comparing a photo ID and a picture of your user’s face. [Learn more](https://docs.stripe.com/identity/selfie).
    - `email` GelatoSessionEmailOptions
      - `require_verification` boolean — Request one time password verification of `provided_details.email`.
    - `id_number` GelatoSessionIdNumberOptions
    - `matching` GelatoSessionMatchingOptions
      - `dob` 'none' | 'similar' — Strictness of the DOB matching policy to apply.
      - `name` 'none' | 'similar' — Strictness of the name matching policy to apply.
    - `phone` GelatoSessionPhoneOptions
      - `require_verification` boolean — Request one time password verification of `provided_details.phone`.
  - `provided_details` GelatoProvidedDetails
    - `email` string — Email of user being verified
    - `phone` string — Phone number of user being verified
  - `redaction` VerificationSessionRedaction
    - `status` 'processing' | 'redacted' | 'validated', required — Indicates whether this object and its related objects have been redacted or not.
  - `related_customer` string, nullable — Customer ID
  - `related_customer_account` string, nullable — The ID of the Account representing a customer.
  - `related_person` GelatoRelatedPerson
    - `account` string, required — Token referencing the associated Account of the related Person resource.
    - `person` string, required — Token referencing the related Person resource.
  - `status` 'canceled' | 'processing' | 'requires_input' | 'verified', required — Status of this VerificationSession. [Learn more about the lifecycle of sessions](https://docs.stripe.com/identity/how-sessions-work).
  - `type` 'document' | 'id_number' | 'verification_flow', required — The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed.
  - `url` string, nullable — The short-lived URL that you use to redirect a user to Stripe to submit their identity information. This URL expires after 48 hours and can only be used once. Don’t store it, log it, send it in emails or expose it to anyone other than the user. Refer to our docs on [verifying identity documents](https://docs.stripe.com/identity/verify-identity-documents?platform=web&type=redirect) to learn how to redirect users to Stripe.
  - `verification_flow` string — The configuration token of a verification flow from the dashboard.
  - `verified_outputs` GelatoVerifiedOutputs
    - `address` Address
      - `city` string, nullable — City, district, suburb, town, or village.
      - `country` string, nullable — Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
      - `line1` string, nullable — Address line 1, such as the street, PO Box, or company name.
      - `line2` string, nullable — Address line 2, such as the apartment, suite, unit, or building.
      - `postal_code` string, nullable — ZIP or postal code.
      - `state` string, nullable — State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)).
    - `dob` GelatoDataVerifiedOutputsDate — Point in Time
      - `day` integer, nullable — Numerical day between 1 and 31.
      - `month` integer, nullable — Numerical month between 1 and 12.
      - `year` integer, nullable — The four-digit year.
    - `email` string, nullable — The user's verified email address
    - `first_name` string, nullable — The user's verified first name.
    - `id_number` string, nullable — The user's verified id number.
    - `id_number_type` 'br_cpf' | 'sg_nric' | 'us_ssn', nullable — The user's verified id number type.
    - `last_name` string, nullable — The user's verified last name.
    - `phone` string, nullable — The user's verified phone number
    - `sex` '[redacted]' | 'female' | 'male' | 'unknown', nullable — The user's verified sex.
    - `unparsed_place_of_birth` string, nullable — The user's verified place of birth as it appears in the document.
    - `unparsed_sex` string, nullable — The user's verified sex as it appears in the document.

## Other responses

- `default` — Error response.

---

[API](https://skmtc.net/stripe/apis/stripe-api-2.md) · [All operations](https://skmtc.net/stripe/apis/stripe-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stripe/stripe-api-2/versions/3653ad45bbec/schema)