Sample - Stripe API
POST/v1/identity/verification_sessions

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

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

11 body fields
client_reference_idstringoptional
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.
expandarray<string>optional
Specifies which fields in the response should be expanded.
metadataobjectoptional
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
optionsobjectoptional
A set of options for the session’s verification checks.
provided_detailsobjectoptional
Details provided about the user being verified. These details might be shown to the user.
related_customerstringoptional
Customer ID
related_customer_accountstringoptional
The ID of the Account representing a customer.
related_personobjectoptional
Tokens referencing a Person resource and its associated account.
return_urlstringoptional
The URL that the user will be redirected to upon completing the verification flow.
typestringoptional
The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed. You must provide a `type` if not passing `verification_flow`.
Allowed:documentid_number
verification_flowstringoptional
The ID of a verification flow from the Dashboard. See https://docs.stripe.com/identity/verification-flows.

2 status codes
200Successful response.
client_reference_idstringoptional
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_secretstringoptional
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.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
idstringrequired
Unique identifier for the object.
last_errorobjectoptional
If present, this property tells you the last error encountered when processing the verification.
last_verification_reportstringoptional
ID of the most recent VerificationReport. [Learn more about accessing detailed verification results.](https://docs.stripe.com/identity/verification-sessions#results)
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadataobjectrequired
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.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:identity.verification_session
optionsobjectoptional
A set of options for the session’s verification checks.
provided_detailsobjectoptional
Details provided about the user being verified. These details may be shown to the user.
redactionobjectoptional
Redaction status of this VerificationSession. If the VerificationSession is not redacted, this field will be null.
related_customerstringoptional
Customer ID
related_customer_accountstringoptional
The ID of the Account representing a customer.
related_personobjectoptional
statusstringrequired
Status of this VerificationSession. [Learn more about the lifecycle of sessions](https://docs.stripe.com/identity/how-sessions-work).
Allowed:canceledprocessingrequires_inputverified
typestringrequired
The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed.
Allowed:documentid_numberverification_flow
urlstringoptional
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_flowstringoptional
The configuration token of a verification flow from the dashboard.
verified_outputsobjectoptional
The user’s verified data.
defaultError response.
errorobjectrequired

Error handling

Any other status is an error: Error response.