The VerificationSession object

Attributes

id string Unique identifier for the object.
object string, value is "identity.verification_session" String representing the object’s type. Objects of the same type share the same value.
client _ reference _ id nullable string 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 nullable string The short-lived client secret used by Stripe.js to show a verification 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 to learn more.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
last _ error nullable object If present, this property tells you the last error encountered when processing the verification.
last _ verification _ report nullable string Expandable ID of the most recent VerificationReport. Learn more about accessing detailed verification results.
livemode boolean If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.
metadata map 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.
options nullable object A set of options for the session’s verification checks.
provided _ details nullable object Includable Details provided about the user being verified. These details may be shown to the user.
redaction nullable object Redaction status of this VerificationSession. If the VerificationSession is not redacted, this field will be null.
related _ customer nullable string Customer ID
related _ customer _ account nullable string The ID of the Account representing a customer.
related _ person nullable object Tokens referencing the related Person resource and it’s associated account.
status enum Status of this VerificationSession. Learn more about the lifecycle of sessions. Possible enum values canceled The VerificationSession has been invalidated for future submission attempts. processing The session has been submitted and is being processed. Most verification checks are processed in less than 1 minute. requires_input Requires user input before processing can continue. verified Processing of all the verification checks are complete and successfully verified.
type enum The type of verification check to be performed. Possible enum values document Document check. id_number ID number check. verification_flow Configuration provided by verification flow
url nullable string 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 to learn how to redirect users to Stripe.
verification _ flow nullable string The configuration token of a verification flow from the dashboard.
verified _ outputs nullable object Includable The user’s verified data.

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

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.

Parameters

client _ reference _ id string 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 map 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 A set of options for the session’s verification checks.
provided _ details object Details provided about the user being verified. These details might be shown to the user.
related _ customer string Customer ID
related _ customer _ account string The ID of the Account representing a customer.
related _ person object Tokens referencing a Person resource and its associated account.
return _ url string The URL that the user will be redirected to upon completing the verification flow.
type enum 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 The ID of a verification flow from the Dashboard. See /identity/verification-flows.

Returns

Returns the created VerificationSession object

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": "..."}

Update a VerificationSession

POST / v1 / identity / verification_sessions /:id

Updates a VerificationSession object.

When the session status is requires_input, you can use this method to update the verification check and options.

Parameters

metadata map 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 A set of options for the session’s verification checks.
provided _ details object Details provided about the user being verified. These details may be shown to the user.
type enum The type of verification check to be performed. Possible enum values document Document check. id_number ID number check.

Returns

Returns the updated VerificationSession object

Response

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