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

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




## OpenAPI

````yaml /openapi/en/verify/verifyapi_v1.yaml post /v1/validations
openapi: 3.1.0
info:
  title: SMS Validation API
  description: >
    Backend API for phone number validation via SMS and other channels. This API
    allows you to validate phone numbers

    by sending SMS verification codes and verifying them. 



    ## Rate Limiting

    The API implements multi-level rate limiting per account, country, and phone
    number.


    ## Offline Proof Verification

    If your tenant has a `verificationSecret` configured, the API returns an
    HMAC proof in the 

    validation response. This proof can be verified offline without calling the
    API (see `/v1/verify-proof` endpoint).
  version: 1.0.0
  contact:
    name: API Support
    email: support@smsmanager.com
servers:
  - url: https://verify-api.smsmanager.com
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Validation
    description: Phone number validation operations
  - name: Tenant
    description: Tenant configuration endpoints
  - name: System
    description: System health and status endpoints
paths:
  /v1/validations:
    post:
      tags:
        - Validation
      summary: Start phone validation
      description: >
        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.
      operationId: startValidation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationRequest'
            examples:
              basic:
                summary: Basic validation request
                value:
                  phoneNumber: '1234567890'
              withPayload:
                summary: With custom payload
                value:
                  phoneNumber: '1234567890'
                  payload:
                    userId: user123
                    source: checkout
      responses:
        '200':
          description: Validation started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
              examples:
                withoutProof:
                  summary: Response without proof (no verificationSecret)
                  value:
                    token: >-
                      61591bd88d8fbe7736bca535809d1216dd71cb0b5cbf2b07e5a08adfbeb5d35b
                    status: pending
                    expiresAt: '2024-01-01T00:10:00.000Z'
                    timestamp: '2024-01-01T00:00:00.000Z'
                withProof:
                  summary: Response with HMAC proof (verificationSecret configured)
                  value:
                    token: >-
                      61591bd88d8fbe7736bca535809d1216dd71cb0b5cbf2b07e5a08adfbeb5d35b
                    status: pending
                    expiresAt: '2024-01-01T00:10:00.000Z'
                    timestamp: '2024-01-01T00:00:00.000Z'
                    proof: >-
                      a2c4e6f8b0d2e4f6a8c0e2f4b6d8f0a2c4e6f8b0d2e4f6a8c0e2f4b6d8f0a2
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ValidationRequest:
      type: object
      required:
        - phoneNumber
      properties:
        phoneNumber:
          type: string
          description: The phone number to validate (digits only, including country code)
          pattern: ^[1-9]\d{6,14}$
          example: '1234567890'
        turnstileToken:
          type: string
          description: >-
            Turnstile verification token (required if tenant has
            requireTurnstile enabled)
          example: 0.abcdefghijklmnopqrstuvwxyz
        payload:
          type: object
          description: Optional custom payload to attach to the validation
          additionalProperties:
            type: string
          example:
            userId: user123
            source: checkout
    ValidationResponse:
      type: object
      required:
        - token
        - status
        - expiresAt
        - timestamp
      properties:
        token:
          type: string
          description: Unique validation token to use for verification
          example: val_7af7215261b8497cb355e617b13f4ef2
        status:
          $ref: '#/components/schemas/ValidationStatus'
        expiresAt:
          type: string
          format: date-time
          description: When this validation expires (typically 10 minutes)
          example: '2024-01-01T00:10:00.000Z'
        timestamp:
          type: string
          format: date-time
          description: When this validation was started (used for HMAC verification)
          example: '2024-01-01T00:00:00.000Z'
        proof:
          type: string
          description: >-
            HMAC proof for offline verification (only if tenant has
            verificationSecret)
          example: a2c4e6f8b0d2e4f6a8c0e2f4b6d8f0a2c4e6f8b0d2e4f6a8c0e2f4b6d8f0a2
    ValidationStatus:
      type: string
      description: Current status of the validation
      enum:
        - pending
        - code_sent
        - verified
        - failed
        - expired
      example: pending
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Invalid code
        error:
          type: string
          description: Error code for programmatic handling
          example: INVALID_CODE
        attemptsRemaining:
          type: integer
          description: >-
            Number of verification attempts remaining (only for verification
            errors)
          example: 3
          minimum: 0
  responses:
    BadRequest:
      description: Bad request - Invalid input data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidPhone:
              summary: Invalid phone number
              value:
                message: Invalid phone number
                error: INVALID_PHONE
            missingField:
              summary: Missing required field
              value:
                message: 'Missing required field: phoneNumber'
                error: MISSING_FIELD
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingKey:
              summary: Missing API key
              value:
                message: Missing X-API-Key header
                error: MISSING_API_KEY
            invalidKey:
              summary: Invalid API key
              value:
                message: Invalid or disabled API key
                error: INVALID_API_KEY
    RateLimited:
      description: Too many requests - Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            tenantLimit:
              summary: Tenant rate limit
              value:
                message: Tenant rate limit exceeded
                error: TENANT_RATE_LIMIT
            phoneLimit:
              summary: Phone number rate limit
              value:
                message: Too many attempts for this phone number
                error: PHONE_RATE_LIMIT
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Internal server error
            error: INTERNAL_ERROR
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your tenant's API key

````