Stripe Identity API
Use Stripe Identity to confirm the identity of global users to prevent fraud, streamline risk operations, and increase trust and safety.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Identity API
description: >-
Use Stripe Identity to confirm the identity of global users to prevent
fraud, streamline risk operations, and increase trust and safety.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/identity/verification_reports:
get:
description: <p>List all verification reports.</p>
operationId: getIdentityVerificationReports
parameters:
- explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Only return VerificationReports of this type
in: query
name: type
required: false
schema:
enum:
- document
- id_number
type: string
x-stripeBypassValidation: true
style: form
- description: >-
Only return VerificationReports created by this VerificationSession
ID. It is allowed to provide a VerificationIntent ID.
in: query
name: verification_session
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetIdentityVerificationReportsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/GelatoVerificationReportList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Identity Verification Reports
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Identity
- Reports
- Verification
/v1/identity/verification_reports/{report}:
get:
description: <p>Retrieves an existing VerificationReport</p>
operationId: getIdentityVerificationReportsReport
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: report
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetIdentityVerificationReportsReportRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/identity.verification_report'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Identity Verification Reports Report
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Identity
- Reports
- Verification
/v1/identity/verification_sessions:
get:
description: <p>Returns a list of VerificationSessions</p>
operationId: getIdentityVerificationSessions
parameters:
- explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
Only return VerificationSessions with this status. [Learn more about
the lifecycle of
sessions](https://stripe.com/docs/identity/how-sessions-work).
in: query
name: status
required: false
schema:
enum:
- canceled
- processing
- requires_input
- verified
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetIdentityVerificationSessionsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/GelatoVerificationSessionList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Identity Verification Sessions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Identity
- Sessions
- Verification
post:
description: >-
<p>Creates a VerificationSession object.</p>
<p>After the VerificationSession is created, display a verification
modal using the session <code>client_secret</code> or send your users to
the session’s <code>url</code>.</p>
<p>If your API key is in test mode, verification checks won’t actually
process, though everything else will occur as if in live mode.</p>
<p>Related guide: <a
href="/docs/identity/verify-identity-documents">Verify your users’
identity documents</a></p>
operationId: postIdentityVerificationSessions
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
options:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostIdentityVerificationSessionsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/identity.verification_session'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Identity Verification Sessions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Identity
- Post
- Sessions
- Verification
/v1/identity/verification_sessions/{session}:
get:
description: >-
<p>Retrieves the details of a VerificationSession that was previously
created.</p>
<p>When the session status is <code>requires_input</code>, you can use
this method to retrieve a valid
<code>client_secret</code> or <code>url</code> to allow
re-submission.</p>
operationId: getIdentityVerificationSessionsSession
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: session
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: >-
#/components/schemas/GetIdentityVerificationSessionsSessionRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/identity.verification_session'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Identity Verification Sessions Session
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Identity
- Sessions
- Verification
post:
description: >-
<p>Updates a VerificationSession object.</p>
<p>When the session status is <code>requires_input</code>, you can use
this method to update the
verification check and options.</p>
operationId: postIdentityVerificationSessionsSession
parameters:
- in: path
name: session
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
options:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostIdentityVerificationSessionsSessionRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/identity.verification_session'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Identity Verification Sessions Session
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Identity
- Post
- Sessions
- Verification
/v1/identity/verification_sessions/{session}/cancel:
post:
description: >-
<p>A VerificationSession object can be canceled when it is in
<code>requires_input</code> <a
href="/docs/identity/how-sessions-work">status</a>.</p>
<p>Once canceled, future submission attempts are disabled. This cannot
be undone. <a href="/docs/identity/verification-sessions#cancel">Learn
more</a>.</p>
operationId: postIdentityVerificationSessionsSessionCancel
parameters:
- in: path
name: session
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostIdentityVerificationSessionsSessionCancelRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/identity.verification_session'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Identity Verification Sessions Session Cancel
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Cancel
- Identity
- Post
- Sessions
- Verification
/v1/identity/verification_sessions/{session}/redact:
post:
description: >-
<p>Redact a VerificationSession to remove all collected information from
Stripe. This will redact
the VerificationSession and all objects related to it, including
VerificationReports, Events,
request logs, etc.</p>
<p>A VerificationSession object can be redacted when it is in
<code>requires_input</code> or <code>verified</code>
<a href="/docs/identity/how-sessions-work">status</a>. Redacting a
VerificationSession in <code>requires_action</code>
state will automatically cancel it.</p>
<p>The redaction process may take up to four days. When the redaction
process is in progress, the
VerificationSession’s <code>redaction.status</code> field will be set to
<code>processing</code>; when the process is
finished, it will change to <code>redacted</code> and an
<code>identity.verification_session.redacted</code> event
will be emitted.</p>
<p>Redaction is irreversible. Redacted objects are still accessible in
the Stripe API, but all the
fields that contain personal data will be replaced by the string
<code>[redacted]</code> or a similar
placeholder. The <code>metadata</code> field will also be erased.
Redacted objects cannot be updated or
used for any purpose.</p>
<p><a href="/docs/identity/verification-sessions#redact">Learn
more</a>.</p>
operationId: postIdentityVerificationSessionsSessionRedact
parameters:
- in: path
name: session
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostIdentityVerificationSessionsSessionRedactRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/identity.verification_session'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Identity Verification Sessions Session Redact
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Identity
- Post
- Redact
- Sessions
- Verification
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
identity.verification_report:
description: >-
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://stripe.com/docs/api/files)
API. To configure and create VerificationReports, use the
[VerificationSession](https://stripe.com/docs/api/identity/verification_sessions)
API.
Related guides: [Accessing verification
results](https://stripe.com/docs/identity/verification-sessions#results).
properties:
created:
description: >-
Time at which the object was created. Measured in seconds since the
Unix epoch.
format: unix-time
type: integer
document:
$ref: '#/components/schemas/gelato_document_report'
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
id_number:
$ref: '#/components/schemas/gelato_id_number_report'
livemode:
description: >-
Has the value `true` if the object exists in live mode or the value
`false` if the object exists in test mode.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- identity.verification_report
type: string
options:
$ref: '#/components/schemas/gelato_verification_report_options'
selfie:
$ref: '#/components/schemas/gelato_selfie_report'
type:
description: Type of report.
enum:
- document
- id_number
type: string
x-stripeBypassValidation: true
verification_session:
description: ID of the VerificationSession that created this report.
maxLength: 5000
nullable: true
type: string
required:
- created
- id
- livemode
- object
title: GelatoVerificationReport
type: object
x-expandableFields:
- document
- id_number
- options
- selfie
x-resourceId: identity.verification_report
identity.verification_session:
description: >-
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://stripe.com/docs/identity/verification-sessions)
properties:
client_secret:
description: >-
The short-lived client secret used by Stripe.js to [show a
verification modal](https://stripe.com/docs/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://stripe.com/docs/identity/verification-sessions#client-secret)
to learn more.
maxLength: 5000
nullable: true
type: string
created:
description: >-
Time at which the object was created. Measured in seconds since the
Unix epoch.
format: unix-time
type: integer
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
last_error:
anyOf:
- $ref: '#/components/schemas/gelato_session_last_error'
description: >-
If present, this property tells you the last error encountered when
processing the verification.
nullable: true
last_verification_report:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/identity.verification_report'
description: >-
ID of the most recent VerificationReport. [Learn more about
accessing detailed verification
results.](https://stripe.com/docs/identity/verification-sessions#results)
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/identity.verification_report'
livemode:
description: >-
Has the value `true` if the object exists in live mode or the value
`false` if the object exists in test mode.
type: boolean
metadata:
additionalProperties:
maxLength: 500
type: string
description: >-
Set of [key-value pairs](https://stripe.com/docs/api/metadata) that
you can attach to an object. This can be useful for storing
additional information about the object in a structured format.
type: object
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- identity.verification_session
type: string
options:
anyOf:
- $ref: '#/components/schemas/gelato_verification_session_options'
description: A set of options for the session’s verification checks.
nullable: true
redaction:
anyOf:
- $ref: '#/components/schemas/verification_session_redaction'
description: >-
Redaction status of this VerificationSession. If the
VerificationSession is not redacted, this field will be null.
nullable: true
status:
description: >-
Status of this VerificationSession. [Learn more about the lifecycle
of sessions](https://stripe.com/docs/identity/how-sessions-work).
enum:
- canceled
- processing
- requires_input
- verified
type: string
type:
description: >-
The type of [verification
check](https://stripe.com/docs/identity/verification-checks) to be
performed.
enum:
- document
- id_number
nullable: true
type: string
x-stripeBypassValidation: true
url:
description: >-
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://stripe.com/docs/identity/verify-identity-documents?platform=web&type=redirect)
to learn how to redirect users to Stripe.
maxLength: 5000
nullable: true
type: string
verified_outputs:
anyOf:
- $ref: '#/components/schemas/gelato_verified_outputs'
description: The user’s verified data.
nullable: true
required:
- created
- id
- livemode
- metadata
- object
- status
title: GelatoVerificationSession
type: object
x-expandableFields:
- last_error
- last_verification_report
- options
- redaction
- verified_outputs
x-resourceId: identity.verification_session
GetIdentityVerificationReportsRequest:
type: object
properties: {}
GelatoVerificationReportList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/identity.verification_report'
type: array
has_more:
description: >-
True if this list has another page of items after this one that can
be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/identity/verification_reports
type: string
GetIdentityVerificationReportsReportRequest:
type: object
properties: {}
GetIdentityVerificationSessionsRequest:
type: object
properties: {}
GelatoVerificationSessionList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/identity.verification_session'
type: array
has_more:
description: >-
True if this list has another page of items after this one that can
be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/identity/verification_sessions
type: string
PostIdentityVerificationSessionsRequest:
type: object
required:
- type
properties:
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
metadata:
additionalProperties:
type: string
description: >-
Set of [key-value pairs](https://stripe.com/docs/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`.
type: object
options:
description: A set of options for the session’s verification checks.
properties:
document:
anyOf:
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-identity-api-openapi.yml