# Start phone validation

Initiates a new phone number validation by sending an message with a verification code.
Returns a validation token that must be used for subsequent verification.

Endpoint: POST /v1/validations
Version: 1.0.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `phoneNumber` (string, required)
    The phone number to validate (digits only, including country code)
    Example: "1234567890"

  - `turnstileToken` (string)
    Turnstile verification token (required if tenant has requireTurnstile enabled)
    Example: "0.abcdefghijklmnopqrstuvwxyz"

  - `payload` (object)
    Optional custom payload to attach to the validation
    Example: {"userId":"user123","source":"checkout"}

## Response 200 fields (application/json):

  - `token` (string, required)
    Unique validation token to use for verification
    Example: "val_7af7215261b8497cb355e617b13f4ef2"

  - `status` (string, required)
    Current status of the validation
    Enum: "pending", "code_sent", "verified", "failed", "expired"

  - `expiresAt` (string, required)
    When this validation expires (typically 10 minutes)
    Example: "2024-01-01T00:10:00.000Z"

  - `timestamp` (string, required)
    When this validation was started (used for HMAC verification)
    Example: "2024-01-01T00:00:00.000Z"

  - `proof` (string)
    HMAC proof for offline verification (only if tenant has verificationSecret)
    Example: "a2c4e6f8b0d2e4f6a8c0e2f4b6d8f0a2c4e6f8b0d2e4f6a8c0e2f4b6d8f0a2"

## Response 400 fields (application/json):

  - `message` (string, required)
    Human-readable error message
    Example: "Invalid code"

  - `error` (string)
    Error code for programmatic handling
    Example: "INVALID_CODE"

  - `attemptsRemaining` (integer)
    Number of verification attempts remaining (only for verification errors)
    Example: 3

## Response 401 fields (application/json):

  - `message` (string, required)
    Human-readable error message
    Example: "Invalid code"

  - `error` (string)
    Error code for programmatic handling
    Example: "INVALID_CODE"

  - `attemptsRemaining` (integer)
    Number of verification attempts remaining (only for verification errors)
    Example: 3

## Response 429 fields (application/json):

  - `message` (string, required)
    Human-readable error message
    Example: "Invalid code"

  - `error` (string)
    Error code for programmatic handling
    Example: "INVALID_CODE"

  - `attemptsRemaining` (integer)
    Number of verification attempts remaining (only for verification errors)
    Example: 3

## Response 500 fields (application/json):

  - `message` (string, required)
    Human-readable error message
    Example: "Invalid code"

  - `error` (string)
    Error code for programmatic handling
    Example: "INVALID_CODE"

  - `attemptsRemaining` (integer)
    Number of verification attempts remaining (only for verification errors)
    Example: 3