CLEAR Verification Sessions API

openapi: 3.1.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:
    SessionInfoOut:
      properties:
        location:
          allOf:
          - $ref: '#/components/schemas/LocationInfo'
          title: Location
          description: Location information gathered from the user's frontend session.
        user_agent:
          type: string
          title: User Agent
          description: The user agent of the browser used
        created_at:
          type: integer
          title: Created At
          description: The time the frontend session was created
        ip:
          type: string
          title: IP Address
          description: The user's IP address
        locale:
          type: string
          title: Locale
          description: The user's locale
        zoneinfo:
          type: string
          title: Time Zone Information
          description: The user's time zone information
      additionalProperties: false
      type: object
      title: SessionInfoOut
      description: Information gathered from the user's frontend session.
    VerificationStatus:
      type: string
      enum:
      - success
      - fail
      - awaiting_user_input
      - deferred
      - processing_data
      - expired
      - awaiting_manual_review
      - manual_success
      - manual_fail
      - canceled
      title: VerificationStatus
      description: The statuses that a verification can be in.
    APIError401Out:
      properties:
        error_type:
          $ref: '#/components/schemas/ErrorType401'
          title: Error Type
          description: '| Error Type | Description |

            | --- | --- |

            | unauthenticated | The request does not have sufficient authentication for this operation. |

            | session_already_exists | An end user session already exists for this verification. The verification needs to be completed on the same device/browser session it was started on. |

            | handoff_unsuccessful | Handoff unsuccessful.  |'
        message:
          type: string
          title: Message
        fields:
          items:
            $ref: '#/components/schemas/FieldErrors'
          type: array
          title: Input Error
          description: This is populated when `error_type` is of `invalid_input`.
          default: []
      additionalProperties: false
      type: object
      title: APIError401Out
    APIError412Out:
      properties:
        error_type:
          $ref: '#/components/schemas/ErrorType412'
          title: Error Type
          description: '| Error Type | Description |

            | --- | --- |

            | precondition_failed | A precondition for this endpoint failed. This error usually occurs when steps of the authentication or verification process are called out of order. |'
        message:
          type: string
          title: Message
        fields:
          items:
            $ref: '#/components/schemas/FieldErrors'
          type: array
          title: Input Error
          description: This is populated when `error_type` is of `invalid_input`.
          default: []
      additionalProperties: false
      type: object
      title: APIError412Out
    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
    APIError429Out:
      properties:
        error_type:
          $ref: '#/components/schemas/ErrorType429'
          title: Error Type
          description: '| Error Type | Description |

            | --- | --- |

            | rate_limit_exceeded | Comes with an HTTP 429 response; too many requests have recently occurred from your system. Rate limits are set very high so that exceeding them should indicate unauthorized access or some other problem. |'
        message:
          type: string
          title: Message
        fields:
          items:
            $ref: '#/components/schemas/FieldErrors'
          type: array
          title: Input Error
          description: This is populated when `error_type` is of `invalid_input`.
          default: []
      additionalProperties: false
      type: object
      title: APIError429Out
    UserProfileMatchingRequestDetailsV2:
      properties:
        name:
          anyOf:
          - $ref: '#/components/schemas/NameMatchingModelV2'
          - type: 'null'
        dob:
          anyOf:
          - type: string
          - type: 'null'
          title: Dob
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        address:
          anyOf:
          - $ref: '#/components/schemas/AddressMatchingModel'
          - type: 'null'
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
      additionalProperties: false
      type: object
      title: User Profile Matching Request Details V2
      description: User profile matching details for verification session.
    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
    WatchlistHitEntityType:
      type: string
      enum:
      - person
      const: person
      title: WatchlistHitEntityType
    VerificationSessionsOut:
      properties:
        verifications:
          items:
            $ref: '#/components/schemas/VerificationSessionOut'
          type: array
          title: Verification Sessions
        links:
          $ref: '#/components/schemas/PaginationLinks'
      type: object
      title: VerificationSessionsOut
    AddressOut:
      properties:
        line1:
          type: string
          title: Line1
          description: Street address (e.g. "123 Main St")
        line2:
          type: string
          title: Line2
          description: Second line of the address, such as the suite, building, or apartment number
        city:
          type: string
          title: City
          description: City
        state:
          type: string
          title: State
          description: Full name of the state, province, or region
        postal_code:
          type: string
          title: Postal Code
          description: Postal code as a string
        country:
          type: string
          title: Country
          description: Country name as a string
      additionalProperties: false
      type: object
      title: Verified Address
      description: Verified address object returned to the vendor.
    VerificationSearchSortField:
      type: string
      enum:
      - created_at
      - updated_at
      title: VerificationSearchSortField
    UserProfileMatchingResponseDetailsV2:
      properties:
        name:
          anyOf:
          - $ref: '#/components/schemas/NameMatchingModel'
          - type: 'null'
        dob:
          anyOf:
          - type: string
          - type: 'null'
          title: Dob
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        address:
          anyOf:
          - $ref: '#/components/schemas/AddressMatchingModel'
          - type: 'null'
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
      additionalProperties: false
      type: object
      title: User Profile Matching Response Details V2
      description: Response object for user profile matching in verification sessions.
    SoraExternalCheckExport:
      properties:
        name:
          type: string
          title: Name
          description: The name of the check as specified in the verification configuration.
        value:
          type: boolean
          title: Value
          description: The corresponding value of the check. The value may be `null` when the check is skipped or unable to evaluate to a deterministic result.
        status:
          type: string
          enum:
          - completed
          - skipped
          - error
          title: Status
          description: Whether this check has been performed or not. completed here means that we were able to perform the check. To see if the check passed or failed, see the `value` field.
        check_result:
          anyOf:
          - type: string
          - type: 'null'
          title: Check Result
          description: 'The granular result of the check that identifies a specific outcome. Possible values: success, failure, indeterminate, not_applicable, awaiting_async_response.'
        additional_details:
          allOf:
          - $ref: '#/components/schemas/SoraExternalCheckAdditionalDetails'
          title: Additional Details
          description: The additional details for this check when available.
        params:
          type: object
          title: Params
          description: Any custom parameters that were configured for the check
        reason_codes:
          items:
            type: string
          type: array
          title: Reason Codes
          description: A list of alphanumerical codes that correspond to various pass or failure reasons.
      additionalProperties: false
      type: object
      required:
      - value
      title: Check
    WatchlistHits:
      properties:
        hits:
          items:
            $ref: '#/components/schemas/WatchlistHit'
          type: array
          title: Hits
          description: ''
        updated_at:
          type: integer
          title: Updated At
          description: A unix timestamp representing the time watchlist hit data was last fetched from data sources
      additionalProperties: false
      type: object
      required:
      - hits
      title: WatchlistHits
    ErrorType412:
      type: string
      enum:
      - precondition_failed
      const: precondition_failed
      title: ErrorType412
    ErrorType401:
      type: string
      enum:
      - unauthenticated
      - session_already_exists
      - handoff_unsuccessful
      title: ErrorType401
    FieldErrors:
      properties:
        location:
          type: string
          title: Location
          description: The location of the error in the request. For example, `body.email` for an invalid email.
        message:
          type: string
          title: Message
          description: Human-readable string describing the error. These are suitable for displaying directly in user interface near the input field.
        received_value:
          title: Received Value
          description: The value received for the field. This attribute is added on a best-effort basis, so for some validation errors it may be blank or non-existent.
      additionalProperties: false
      type: object
      required:
      - location
      - message
      - received_value
      title: FieldErrors
    SoraExternalCheckAdditionalDetails:
      properties:
        watchlist_hits:
          allOf:
          - $ref: '#/components/schemas/WatchlistHits'
          title: Watchlist Hits
          description: Watchlist hits
      additionalProperties: false
      type: object
      title: SoraExternalCheckAdditionalDetails
      description: Additional details returned for some checks.
    NameMatchingModelV2:
      properties:
        first_name:
          anyOf:
          - type: string
          - type: 'null'
          title: First Name
        last_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Name
      additionalProperties: false
      type: object
      title: Name Matching Model V2
      description: Parameters for creating a name for matching, excluding middle name.
    CustomFieldsIn:
      properties:
        custom_fields:
          additionalProperties:
            type: string
          type: object
          title: Custom Fields
          description: Custom fields specified by you as key-value pairs.
      additionalProperties: false
      type: object
      required:
      - custom_fields
      title: CustomFieldsIn
    APIError500Out:
      properties:
        error_type:
          $ref: '#/components/schemas/ErrorType500'
          title: Error Type
          description: '| Error Type | Description |

            | --- | --- |

            | unexpected_error | An unexpected error occurred while processing request. Appears with 5XX errors. |'
        message:
          type: string
          title: Message
        fields:
          items:
            $ref: '#/components/schemas/FieldErrors'
          type: array
          title: Input Error
          description: This is populated when `error_type` is of `invalid_input`.
          default: []
      additionalProperties: false
      type: object
      title: APIError500Out
    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
  

# --- 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