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

# Create a verification

> Registers a user and returns a `verification_url`. Redirect or link your
user to this URL so they can complete the liveness check. After
completion, the user is redirected back to `redirect` with `vy_token`
and `vy_status` query parameters appended.




## OpenAPI

````yaml /v2/openapi.yaml post /v2/verification/create
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/create:
    post:
      summary: Create a verification
      description: |
        Registers a user and returns a `verification_url`. Redirect or link your
        user to this URL so they can complete the liveness check. After
        completion, the user is redirected back to `redirect` with `vy_token`
        and `vy_status` query parameters appended.
      operationId: createVerification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerificationRequest'
      responses:
        '200':
          description: Verification created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVerificationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    CreateVerificationRequest:
      type: object
      properties:
        external_id:
          type: string
          description: >-
            Your application's user identifier. If omitted, a UUID is generated
            automatically.
          example: user_123
        redirect:
          type: string
          format: uri
          description: |
            URL the user is redirected to after completing verification.
            `vy_token` and `vy_status` query parameters are appended.
          example: https://yourapp.com/done
        region:
          type: string
          description: |
            Limits each verified person to one account per region, preventing
            duplicate accounts and fraud within the same context. Use this when
            you need one real human per context: e.g. one account per
            competition, one response per form, or one player per server. Users
            already verified can connect to new regions instantly without
            redoing the liveness check. If omitted, each person is limited to
            one account across your entire integration.
          example: event_2026_austin
        phone:
          type: string
          description: |
            Optional E.164 phone number. When supplied, the returned
            `verification_url` lands the user directly on the liveness check
            with no phone-OTP step (instead of the usual `/invite` landing
            page). Use this only when you've already verified the number
            out-of-band (e.g. your own SMS/login flow); the URL is the
            trust anchor for the shortcut, so deliver it over a channel
            you've already authenticated. Test phone numbers from the
            sandbox work today; real-phone bypass requires server-side OTP
            suppression that isn't shipped yet.
          example: '+12105550142'
    CreateVerificationResponse:
      type: object
      properties:
        verification_url:
          type: string
          format: uri
          description: >
            URL to send the user to for verification. Two possible shapes:


            - **No `phone` in the request**:
            `https://verifyyou.com/invite?session_id=<id>`, landing page →
            phone-OTP → liveness.

            - **`phone` supplied**:
            `https://verifyyou.com/verify?session_id=<id>&t=<opaque>`, skips the
            phone-OTP step and lands the user directly on the liveness check.


            Always send your user to whichever URL came back; the path is an
            implementation detail.
          example: https://verifyyou.com/invite?session_id=zsjmq6
        external_id:
          type: string
          description: >-
            The `external_id` used for this verification. Matches what you sent,
            or the auto-generated ID if omitted.
          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
    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.

````