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

# Generate a test phone number

> Generate a random test phone number and its corresponding verification
code. Works without authentication (unauthenticated access is heavily
rate limited). Also accepts demo/sandbox API keys.

Test phone numbers use reserved ranges that never send real SMS:
- **US**: `+1{area_code}555-01xx` (NANP fictional block)
- **Global**: `+99901xxxxxxx` (ITU E.164 test range)

The verification code is always the last 6 digits of the phone number.




## OpenAPI

````yaml /v2/openapi.yaml post /v2/sandbox/phone-number
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/sandbox/phone-number:
    post:
      summary: Generate a test phone number
      description: |
        Generate a random test phone number and its corresponding verification
        code. Works without authentication (unauthenticated access is heavily
        rate limited). Also accepts demo/sandbox API keys.

        Test phone numbers use reserved ranges that never send real SMS:
        - **US**: `+1{area_code}555-01xx` (NANP fictional block)
        - **Global**: `+99901xxxxxxx` (ITU E.164 test range)

        The verification code is always the last 6 digits of the phone number.
      operationId: sandboxGeneratePhoneNumber
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratePhoneNumberRequest'
      responses:
        '200':
          description: Test phone number generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratePhoneNumberResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - apiKey: []
        - {}
components:
  schemas:
    GeneratePhoneNumberRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - us
            - global
          description: Type of test phone number to generate.
          default: global
          example: us
        area_code:
          type: string
          description: 3-digit US area code (only used when type is `us`).
          default: '210'
          example: '210'
    GeneratePhoneNumberResponse:
      type: object
      properties:
        phone_number:
          type: string
          description: The generated test phone number in E.164 format.
          example: '+12105550142'
        verification_code:
          type: string
          description: The verification code for this test number (last 6 digits).
          example: '550142'
    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
    Forbidden:
      description: Demo/sandbox API key required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: failure
            failure_code: DEMO_ACCOUNT_REQUIRED
            failure_reason: Sandbox endpoints are only available for demo accounts
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: API-KEY
      description: Your VerifyYou API key.

````