CLEAR Verification Sessions API

openapi: 3.2.0
info:
  title: CLEAR1 Verification Sessions API
  description: Everything you need to get started with CLEAR1.
  version: '1.1'
  x-logo:
    url: https://static-verified.clearme.com/CLEAR1_Logo_Horizontal_2Color_RGB.png
servers:
- url: https://verified.clearme.com/v1
security:
- Authorization_Bearer: []
tags:
- name: Verification Sessions
  description: ''
paths:
  /verification_sessions:
    post:
      tags:
      - Verification Sessions
      summary: Create Verification Session
      operationId: create_verification_session
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationOptions'
              default:
                auth_type: sms
                send_creator_email: true
                sandbox: false
      responses:
        '200':
          description: Returns a Verification Session object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationSessionOut'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError400Out'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError401Out'
          description: Unauthorized
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError412Out'
          description: Precondition Failed
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError429Out'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError500Out'
          description: Internal Server Error
    get:
      tags:
      - Verification Sessions
      summary: List Verification Sessions
      description: '**⚠️ Deprecation Notice:**

        >

        > This endpoint is deprecated and will be removed in the future. For new integrations we recommend

        > using the [Search Verification Sessions](https://docs.clearme.com/reference/search_verification_sessions)

        > endpoint instead.'
      operationId: list_verifications
      deprecated: true
      parameters:
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          description: Number of records per page.
          default: 25
          title: Page Size
        description: Number of records per page.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: Page number of the current page.
          default: 1
          title: Page
        description: Page number of the current page.
      - name: sort_descending
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to sort in descending (True) or ascending (False) order. By default, sorts descending.
          default: true
          title: Sort Descending
        description: Whether to sort in descending (True) or ascending (False) order. By default, sorts descending.
      - name: sort_by
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortByOptions'
          description: Property to sort by. "created_at" by default.
          enum:
          - created_at
          - updated_at
          default: created_at
        description: Property to sort by. "created_at" by default.
      - name: search_term
        in: query
        required: false
        schema:
          type: string
          description: 'Search term for filtering results. Supports searching by a trait the user has consented to share (email, phone, name, etc.). Examples: ''my.email@example.com'', ''+15551234567'', ''Alex Taylor''.'
          default: ''
          title: Search Term
        description: 'Search term for filtering results. Supports searching by a trait the user has consented to share (email, phone, name, etc.). Examples: ''my.email@example.com'', ''+15551234567'', ''Alex Taylor''.'
      responses:
        '200':
          description: Returns a list of Verification Session objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationSessionsOut'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError400Out'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError401Out'
          description: Unauthorized
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError412Out'
          description: Precondition Failed
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError429Out'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError500Out'
          description: Internal Server Error
  /verification_sessions/{id}/custom_fields:
    post:
      tags:
      - Verification Sessions
      summary: Add Custom Fields to Verification Session
      operationId: add_custom_fields_verification_vendor_backend
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: ID
          description: Verification Session ID
        description: Verification Session ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldsIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationSessionOut'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError400Out'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError401Out'
          description: Unauthorized
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError412Out'
          description: Precondition Failed
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError429Out'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError500Out'
          description: Internal Server Error
  /verification_sessions/{id}:
    get:
      tags:
      - Verification Sessions
      summary: Get Verification Session
      description: 'Retrieve verification session details.


        **Sensitive Data Handling:**

        - By default, SPII such as SSNs and government ID images are not revealed in the response

        - To reveal this data, set the `reveal_sensitive_data` query parameter to `true`


        **⚠️ Deprecation Notice:**

        The previous approach of using `https://secure.verified.clearme.com`

        to reveal sensitive PII is being deprecated. Please migrate to using the `reveal_sensitive_data`

        query parameter instead.'
      operationId: get_verification
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: ID
          description: Verification Session ID
        description: Verification Session ID
      - name: reveal_sensitive_data
        in: query
        required: false
        schema:
          type: boolean
          description: Set to true to reveal sensitive data such as SSNs and government ID images.
          title: Reveal Sensitive Data
        description: Set to true to reveal sensitive data such as SSNs and government ID images.
      responses:
        '200':
          description: Returns a Verification Session object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationSessionOut'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError400Out'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError401Out'
          description: Unauthorized
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError412Out'
          description: Precondition Failed
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError429Out'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError500Out'
          description: Internal Server Error
    put:
      tags:
      - Verification Sessions
      summary: Submit User Profile Information for Verification Session
      operationId: update_verification_session
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: ID
          description: Verification Session ID
        description: Verification Session ID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationUpdateOptions'
              default: {}
      responses:
        '200':
          description: Returns a Verification Session object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationSessionOut'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError400Out'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError401Out'
          description: Unauthorized
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError412Out'
          description: Precondition Failed
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError429Out'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError500Out'
          description: Internal Server Error
  /verification_sessions/search:
    get:
      tags:
      - Verification Sessions
      summary: Search Verification Sessions with Advanced Filters
      description: 'Search verification sessions with flexible filtering.


        Filters combine using AND logic between different filter types, and OR logic

        within each filter''s values. For example, filtering by status=[success, fail]

        and email=[user1@example.com, user2@example.com] returns sessions that match

        (success OR fail) AND (either email).


        In addition to the parameters listed below, this endpoint also supports searching

        by your custom fields. To filter by a custom field value, specify the field name

        as a query parameter prefixed with `custom_`. For example, to search for verifications

        with a specific value for the custom field `store_id`, add `custom_store_id=xyz` as

        a query parameter in your request.'
      operationId: search_verification_sessions
      parameters:
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of results to return per page
          default: 25
          title: Pagesize
        description: Number of results to return per page
      - name: searchAfter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor (encodes sort value and record ID)
          title: Searchafter
        description: Pagination cursor (encodes sort value and record ID)
      - name: sortField
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/VerificationSearchSortField'
          description: Field to sort results by
          default: updated_at
        description: Field to sort results by
      - name: sortDirection
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/VerificationSearchSortDirection'
          description: Direction to sort results
          default: desc
        description: Direction to sort results
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/VerificationSessionStatus'
          - type: 'null'
          description: Filter by verification session status
          title: Status
        description: Filter by verification session status
      - name: projectId
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by project IDs
          title: Projectid
        description: Filter by project IDs
      - name: email
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by email addresses
          title: Email
        description: Filter by email addresses
      - name: phone
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by phone numbers (partial match)
          title: Phone
        description: Filter by phone numbers (partial match)
      - name: name
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by names (partial match)
          title: Name
        description: Filter by names (partial match)
      - name: flowId
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by verification session IDs
          title: Flowid
        description: Filter by verification session IDs
      - name: flowToken
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by flow tokens
          title: Flowtoken
        description: Filter by flow tokens
      - name: userId
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by user IDs
          title: Userid
        description: Filter by user IDs
      - name: startTime
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Filter by verifcations updated after this timestamp, measured in seconds since the Unix epoch
          title: Starttime
        description: Filter by verifcations updated after this timestamp, measured in seconds since the Unix epoch
      - name: endTime
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Filter by verifcations updated before this timestamp, measured in seconds since the Unix epoch
          title: Endtime
        description: Filter by verifcations updated before this timestamp, measured in seconds since the Unix epoch
      responses:
        '200':
          description: Returns a list of Verification Session objects matching the search criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeysetPaginatedVerificationSessionsOut'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError400Out'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError401Out'
          description: Unauthorized
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError412Out'
          description: Precondition Failed
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError429Out'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError500Out'
          description: Internal Server Error
components:
  schemas:
    DocumentOut:
      properties:
        nationality:
          type: string
          title: Nationality
        document_type:
          allOf:
          - $ref: '#/components/schemas/SoraDocumentTypeEnum'
          description: The type of the user's document.
        document_subtypes:
          items:
            type: string
          type: array
          title: Document Subtypes
          description: A list of subtypes from the document
        issuing_country:
          type: string
          title: Issuing Country
          description: The ISO 3166 alpha-3 country code of issue of the document
        issuing_subdivision:
          type: string
          title: Issuing Subdivision
          description: The ISO 3166 subdivision (state/provence/etc) issuer of the document
        document_number:
          type: string
          title: Document Number
          description: The document number scanned from the document
        date_of_expiry:
          allOf:
          - $ref: '#/components/schemas/Date'
          title: Date Of Expiry
          description: The date of expiration of the document
        gender:
          type: string
          title: Gender
          description: The gender scanned from the document
        address:
          allOf:
          - $ref: '#/components/schemas/AddressOut'
          description: The address scanned from the document
        date_of_birth:
          allOf:
          - $ref: '#/components/schemas/Date'
          title: Date Of Birth
          description: The date of birth scanned from the document
        first_name:
          type: string
          title: First Name
          description: The first name scanned from the document
        last_name:
          type: string
          title: Last Name
          description: The last name scanned from the document
        middle_name:
          type: string
          title: Middle Name
          description: The middle name scanned from the document
        full_name:
          type: string
          title: Full Name
          description: The full name scanned from the document
      additionalProperties: false
      type: object
      title: Verified Document
      description: Verified document object returned to the vendor.
    ErrorType400:
      type: string
      enum:
      - invalid_argument
      - invalid_input
      - invalid_content_type
      - json_decode_error
      - json_decode_error
      - invalid_cookie
      - error_sending_handoff_with_sms
      title: ErrorType400
    VerificationSessionOut:
      properties:
        id:
          type: string
          title: Verification Session ID
          description: Unique identifier for the verification session object.
        object_name:
          type: string
          title: Object Name
          description: The object type, which is `verification_session`.
          default: verification_session
        authenticated:
          type: boolean
          title: Authenticated
          description: Whether or not the user is authenticated.
        authentication_methods:
          items:
            type: string
          type: array
          title: Authentication Methods
          description: List of methods that the user authenticated with. May be `webauthn`, `email`, `sms_otp`.
        activated_authentication_methods:
          items:
            type: string
          type: array
          title: Activated Authentication Methods
          description: List of methods that the user activated, i.e. set up but did not use as a pre-existing credential. May be `webauthn`, `totp`.
          default: []
        checks:
          items:
            $ref: '#/components/schemas/SoraExternalCheckExport'
          type: array
          title: Checks
          description: List of checks that were performed on the user's data, along with their results. For more details see the Check object below. For the complete list of supported checks and descriptions, see Supported Identity Checks).
        check_metadata:
          items:
            type: string
          type: array
          title: Check Metadata
          description: A list of error codes that correspond to particular events that influenced whether a check passed or failed.
        completed_at:
          type: integer
          title: Completed At
          description: Time at which the verification session was completed, measured in seconds since the Unix epoch. This field will be empty if the user has not completed the verification session.
        created_at:
          type: integer
          title: Created At
          description: Time at which the verification session was created, measured in seconds since the Unix epoch.
        email:
          type: string
          title: Email
          description: The user's verified email. This field will be empty if the user has not verified their email.
        expires_at:
          type: integer
          title: Expires At
          description: Time at which when the verification session expires, measured in seconds since the Unix epoch. Expired verification sessions cannot be updated.
        fields_to_collect:
          items:
            type: string
          type: array
          title: Fields To Collect
          description: The required fields to complete the current step of the verification.
          default: []
        ip:
          items:
            type: string
          type: array
          title: IP Addresses
          description: List of the user's ip addresses they used to access this verification session.
          default: []
        phone:
          type: string
          title: Phone
          description: The user's verified phone number, in E.164 format. This field will be empty if the user has not verified their phone number.
        redirect_url:
          type: string
          title: Redirect Url
          description: If present, users will be redirected to this url upon completing the verification session.
        status:
          $ref: '#/components/schemas/VerificationStatus'
          description: The status of the user's progress through the verification session. For a description of the possible values, see the Verification Status Descriptions section below.
        token:
          type: string
          title: Token
          description: The verification session token. Pass it to your front-end to launch the Sora UI.
        updated_at:
          type: integer
          title: Updated At
          description: Time at which the verification session was most recently updated, measured in seconds since the Unix epoch.
        user_agent:
          items:
            type: string
          type: array
          title: User Agent
          description: List of user agents that have accessed this verification session.
          default: []
        user_created:
          type: boolean
          title: User Created
          description: Whether or not the user is signing up for a new account.
          default: false
        user_id:
          type: string
          title: User Id
          description: Unique identifier for this specific user. This field is empty if the user has not successfully been authenticated.
        traits:
          allOf:
          - $ref: '#/components/schemas/TraitsOut'
          title: Traits
          description: A TraitsOut object that contains user information. This field is populated once all traits required to make a verification decision are collected. See below for more details.
        project_id:
          type: string
          title: Project Id
          description: Unique identifier of the deployed project used for this session.
        user_profile_information:
          allOf:
          - $ref: '#/components/schemas/UserProfileMatchingResponseDetailsV2'
          description: User Profile Information for client record matching
        custom_fields:
          type: object
          title: Custom Fields
          description: Custom fields specified by you as key-value pairs.
        user_profile_match_status:
          type: string
          title: User Profile Match Status
          description: User Profile matching status. This field is populated when the user profile matching is enabled for the project
        idv_status:
          type: string
          title: Idv Status
          description: User verification status
        sessions:
          anyOf:
          - items:
              $ref: '#/components/schemas/SessionInfoOut'
            type: array
          - type: 'null'
          title: Sessions
          description: Info about the user sessions for this verification
      additionalProperties: false
      type: object
      title: Verification Session
      description: We return data in the following schema for our Verification Session routes.
    NameMatchingModel:
      properties:
        first_name:
          anyOf:
          - type: string
          - type: 'null'
          title: First Name
        last_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Name
        middle_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Middle Name
      additionalProperties: false
      type: object
      title: Name Matching Model
      description: Parameters for creating a name for matching
    LocationInfo:
      properties:
        country:
          type: string
          title: Country
          description: Country name as a string
        country_iso:
          type: string
          title: Country ISO Code
          description: Country ISO 3166 2-letter code as a string
        subdivision:
          type: string
          title: Subdivision
          description: Subdivision name as a string
        subdivision_type:
          type: string
          title: Subdivision Type
          description: The kind of subdivision, e.g. state, province, etc.
        city:
          type: string
          title: City
          description: City name as a string
        lat:
          type: string
          title: Lat
          description: Latitude parsed from the request
        lon:
          type: string
          title: Lon
          description: Longitude parsed from the request
      additionalProperties: false
      type: object
      title: LocationInfo
      description: 'Information about where a request came from parsed from its IP or other request-level

        information.'
    VerificationUpdateOptions:
      properties:
        user_profile_information:
          $ref: '#/components/schemas/UserProfileMatchingRequestDetailsV2'
          description: User Profile Information for client record matching
      additionalProperties: false
      type: object
      title: VerificationUpdateOptions
    KeysetPaginatedVerificationSessionsOut:
      properties:
        verifications:
          items:
            $ref: '#/components/schemas/VerificationSessionOut'
          type: array
          title: Verification Sessions
        links:
          $ref: '#/components/schemas/PaginationLinks'
        searchAfter:
          anyOf:
          - type: string
          - type: 'null'
          title: Searchafter
          description: Cursor for retrieving the next page of results. Pass this value to the searchAfter query parameter in your next request to continue pagination. This cursor encodes the position in the result set based on the current sort order. If there are no results this field will contain the searchAfter param that was sent with the request.
      type: object
      title: KeysetPaginatedVerificationSessionsOut
    VerificationSessionStatus:
      type: string
      enum:
      - success
      - fail
      - awaiting_user_profile_information
      - awaiting_user_input
      - processing_data
      - expired
      - awaiting_manual_review
      - manual_success
      - manual_fail
      - deferred
      - canceled
      title: VerificationSessionStatus
      description: The statuses that a a verification session can be in.
    WatchlistHitDetails:
      properties:
        name:
          items:
            type: string
          type: array
          title: Name
          description: ''
        alias:
          items:
            type: string
          type: array
          title: Alias
          description: ''
        country:
          items:
            type: string
          type: array
          title: Country
          description: List of ISO 3 country codes associated with the person
        address:
          items:
            $ref: '#/components/schemas/AddressOut'
          type: array
          title: Address
          description: List of addresses associated with the person
        date_of_birth:
          items:
            $ref: '#/components/schemas/WatchlistDate'
          type: array
          title: Date Of Birth
          description: ''
        date_of_death:
          items:
            $ref: '#/components/schemas/WatchlistDate'
          type: array
          title: Date Of Death
          description: ''
        place_of_birth:
          items:
            type: string
          type: array
          title: Place Of Birth
          description: List of places of birth of the person
        gender:
          items:
            type: string
          type: array
          title: Gender
          description: List of human genders of the person, as represented in government and other databases.
        nationality:
          items:
            type: string
          type: array
          title: Nationality
          description: List ISO 3 codes of the person's nationalities
        position:
          items:
            type: string
          type: array
          title: Position
          description: List of political, industrial, or other positions occupied by the person
        passport_number:
          items:
            type: string
          type: array
          title: Passport Number
          description: ''
        id_number:
          items:
            type: string
          type: array
          title: Id Number
          description: ''
        notes:
          items:
            type: string
          type: array
          title: Notes
          description: Notes on the person from the data sources
        created_at:
          items:
            $ref: '#

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