Stripe Verification API

openapi: 3.0.0
info:
  title: Stripe Accounts Account Verification API
  description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
  contact:
    email: dev-platform@stripe.com
    name: Stripe Dev Platform Team
    url: https://stripe.com
  termsOfService: https://stripe.com/us/terms/
  version: '2023-10-16'
  x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Verification
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:
      - 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:
      - 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:
      - 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:
      - 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:
      - 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:
      - 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:
      - 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:
      - Verification
components:
  schemas:
    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
    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
    error:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
      - error
      type: object
    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:
              - properties:
                  allowed_types:
                    items:
                      enum:
                      - driving_license
                      - id_card
                      - passport
                      type: string
                    type: array
                  require_id_number:
                    type: boolean
                  require_live_capture:
                    type: boolean
                  require_matching_selfie:
                    type: boolean
                title: document_options
                type: object
              - enum:
                - ''
                type: string
          title: session_options_param
          type: object
        return_url:
          description: The URL that the user will be redirected to upon completing the verification flow.
          type: string
        type:
          description: The type of [verification check](https://stripe.com/docs/identity/verification-checks) to be performed.
          enum:
          - document
          - id_number
          type: string
          x-stripeBypassValidation: true
    PostIdentityVerificationSessionsSessionRedactRequest:
      type: object
      properties:
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
    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
    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
    GetIdentityVerificationSessionsSessionRequest:
      type: object
      properties: {}
    PostIdentityVerificationSessionsSessionRequest:
      type: object
      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:
              - properties:
                  allowed_types:
                    items:
                      enum:
                      - driving_license
                      - id_card
                      - passport
                      type: string
                    type: array
                  require_id_num

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-verification-api-openapi.yml