> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verifyyou.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check verification status

> Look up whether a verification has been completed. Supply either the
short-lived `token` from the redirect callback, or the `external_id`
you used when creating the verification.

An in-flight verification (created but the user hasn't finished the
liveness check yet) returns `200` with `verification_complete: false`,
safe to poll. `404` is only returned when the token or `external_id`
has no matching verification at all.

Tokens expire after 15 minutes. After expiry, use `external_id` instead.




## OpenAPI

````yaml /v2/openapi.yaml post /v2/verification/status
openapi: 3.1.0
info:
  title: VerifyYou V2 API
  version: 2.1.0
  description: |
    Two API calls to verify a user is a real, unique human.

    1. Create a verification: get back a URL to send your user to.
    2. Check the status: confirm the result with the token from the redirect.
servers:
  - url: https://api.connect.verifyyou.com
    description: Production
  - url: http://localhost:8083
    description: Local
security:
  - apiKey: []
paths:
  /v2/verification/status:
    post:
      summary: Check verification status
      description: |
        Look up whether a verification has been completed. Supply either the
        short-lived `token` from the redirect callback, or the `external_id`
        you used when creating the verification.

        An in-flight verification (created but the user hasn't finished the
        liveness check yet) returns `200` with `verification_complete: false`,
        safe to poll. `404` is only returned when the token or `external_id`
        has no matching verification at all.

        Tokens expire after 15 minutes. After expiry, use `external_id` instead.
      operationId: getVerificationStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationStatusRequest'
      responses:
        '200':
          description: Status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          description: Token has expired. Use `external_id` instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: failure
                failure_code: EXPIRED
                failure_reason: Verification token has expired. Use external_id instead.
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    VerificationStatusRequest:
      type: object
      description: Provide either `token` or `external_id` (at least one is required).
      properties:
        token:
          type: string
          description: >-
            Short-lived token from the `vy_token` redirect query parameter.
            Expires after 15 minutes.
          example: vt:a1b2c3d4-e5f6-7890-abcd-ef1234567890
        external_id:
          type: string
          description: >-
            The `external_id` used when creating the verification. Use this for
            lookups after the token expires.
          example: user_123
    VerificationStatusResponse:
      type: object
      properties:
        verification_complete:
          type: boolean
          description: '`true` if the user passed the liveness check.'
        external_id:
          type: string
          description: The `external_id` associated with this verification.
          example: user_123
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - failure
        failure_code:
          type: string
          description: Machine-readable error code.
        failure_reason:
          type: string
          description: Human-readable error message.
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: failure
            failure_code: INVALID_API_ACCESS
            failure_reason: token or external_id required
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: failure
            failure_code: INVALID_API_KEY
            failure_reason: API key is missing or invalid
    NotFound:
      description: |
        No verification exists for the supplied token or `external_id`. An
        in-flight verification (not yet completed) returns `200` with
        `verification_complete: false`; only truly unknown identifiers hit
        this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: failure
            failure_code: DOES_NOT_EXIST
            failure_reason: Token not found
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: failure
            failure_code: INTERNAL_ERROR
            failure_reason: An unexpected error occurred
    ServiceUnavailable:
      description: Service is temporarily unavailable for maintenance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: failure
            failure_code: SERVICE_TEMPORARILY_UNAVAILABLE
            failure_reason: >-
              Service is temporarily unavailable for maintenance. Please try
              again later.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: API-KEY
      description: Your VerifyYou API key.

````