openapi: 3.0.3
info:
  title: Data Checks Phone Validation API
  version: "1.0"
  description: |
    This API validates, normalises, and enriches phone numbers in real time to ensure
    high data quality across online forms, CRMs, and internal workflows. It converts raw
    inputs into the standard E.164 format while extracting critical metadata, including
    country of origin, location, line type (e.g., mobile or landline), and carrier network
    where available. By assessing multiple real-time signals, the API delivers a definitive
    usability status to help systems automatically filter out invalid entries and maintain a
    clean contact database.

servers:
  - url: https://api.data-checks.com

security:
  - bearerAuth: []

paths:
  /v1/phone:
    post:
      operationId: validatePhone
      summary: Validate a phone number
      tags:
        - Phone validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PhoneValidationRequest"
            example:
              phone: "07123 456789"
              iso_country: GB
      responses:
        "200":
          description: Validation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PhoneValidationResponse"
              example:
                input: "07123 456789"
                normalized: "+447123456789"
                is_valid: true
                reason: active
                type: Mobile
                provider: Vodafone
                location: United Kingdom
                iso_country: GB
                remaining_credits: 99
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missing:
                  value:
                    error: missing_api_key
                invalid:
                  value:
                    error: invalid_api_key
        "402":
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: insufficient_credits
        "403":
          description: Key restriction or browser key mismatch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                ip:
                  value:
                    error: ip_not_allowed
                browserKey:
                  value:
                    error: browser_side_key_required
                originRequired:
                  value:
                    error: origin_required
                originNotAllowed:
                  value:
                    error: origin_not_allowed
        "422":
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: validation_failed
        "429":
          description: Rate or daily limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                rate:
                  value:
                    error: rate_limit_exceeded
                daily:
                  value:
                    error: daily_limit_exceeded
        "503":
          description: Service unavailable (empty body)

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from the dashboard (API Keys). Prefix with `Bearer `.

  schemas:
    PhoneValidationRequest:
      type: object
      required:
        - phone
      properties:
        phone:
          type: string
          maxLength: 64
          description: Number to validate. Spaces, +, brackets, and dashes are accepted.
        iso_country:
          type: string
          minLength: 2
          maxLength: 2
          pattern: "^[A-Za-z]{2}$"
          description: |
            Default country (ISO 3166-1 alpha-2) when the number has no + prefix.
            Defaults to GB if omitted.

    PhoneValidationResponse:
      type: object
      required:
        - input
        - normalized
        - is_valid
        - reason
        - remaining_credits
      properties:
        input:
          type: string
          description: Original submitted value.
        normalized:
          type: string
          nullable: true
          description: Canonical E.164 form.
        is_valid:
          type: boolean
        reason:
          type: string
          enum:
            - active
            - live
            - qualified
            - unallocated
            - inactive
            - ceased
            - syntax
            - unsupported
        type:
          type: string
          nullable: true
          description: Line type (e.g. Landline, Mobile).
        provider:
          type: string
          nullable: true
          description: Network or service provider when available.
        location:
          type: string
          nullable: true
          description: Location associated with the number.
        iso_country:
          type: string
          nullable: true
          description: ISO 3166-1 alpha-2 country code.
        remaining_credits:
          type: integer
          description: Phone credits remaining after this validation.

    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
