openapi: 3.2.0
info:
  title: Numbers Online Phone Intelligence Reference API
  description: Phone number parsing, validation, and inbound caller-intelligence as a supplementary signal.
  version: 1.0.0
  contact:
    name: Phone Numbers Online
    url: https://numbers.online
servers:
- url: https://numbers.online
  description: Production server
- url: http://localhost:3000
  description: Development server
tags:
- name: Reference
  description: Reference data and examples
paths:
  /api/v1/countries:
    get:
      tags:
      - Reference
      summary: List supported countries
      description: Reference list of supported countries with calling codes and example numbers. Free (priced $0). Requires the `parse` use case. The legacy `/api/countries` path is a frozen alias with a `{success:}` envelope.
      operationId: v1Countries
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: List of supported countries
          content:
            application/json:
              schema:
                type: object
                properties:
                  schema_version:
                    type: string
                    example: '2026-06-21'
                  count:
                    type: integer
                  countries:
                    type: array
                    items:
                      $ref: '#/components/schemas/Country'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/countries:
    get:
      tags:
      - Reference
      summary: List supported countries (legacy alias)
      deprecated: true
      description: Frozen permanent alias of `GET /api/v1/countries`, kept for existing integrations — same data, but wrapped in the legacy `{success:}` envelope. New integrations should use the v1 path. Get a list of all supported countries with their calling codes and example phone numbers.
      operationId: listCountries
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: List of supported countries
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  count:
                    type: integer
                  countries:
                    type: array
                    items:
                      $ref: '#/components/schemas/Country'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
          description: Legacy field emitted ONLY by the pre-v1 parse family (/api/parse, /api/parse/bulk, /api/countries). /v1 routes return only `error` — do not depend on `success` there.
        error:
          type: string
          description: Human-readable error message (prose — switch on `code`, not on this string).
        code:
          type: string
          enum:
          - missing_key
          - invalid_key
          - use_case_forbidden
          - rate_limited_key
          - rate_limited_pool
          - rate_limited_ip
          - signature_invalid
          - insufficient_balance
          - account_suspended
          - paid_verification_required
          - receipt_invalid
          description: 'Stable machine-readable error code (added 2026-06-12, additive — older errors may omit it). See the "Error codes" section in the API description for the full table. A valid key on the wrong use case returns 403 use_case_forbidden (not 401): re-authing will not fix a permissions problem.'
        retry_after_seconds:
          type: integer
          description: 'Present on 429s: seconds until the window resets (mirrors the Retry-After header).'
      required:
      - error
    Country:
      type: object
      properties:
        code:
          type: string
          description: ISO 3166-1 alpha-2 country code
        name:
          type: string
          description: Country name
        callingCode:
          type: string
          description: Country calling code
        exampleNumber:
          type:
          - string
          - 'null'
          description: Example phone number in E.164 format
        exampleNational:
          type:
          - string
          - 'null'
          description: Example phone number in national format
  responses:
    RateLimited:
      description: Per-key rate limit exceeded. Retry after the number of seconds in the Retry-After header.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication
    CidQueryKeyAuth:
      type: apiKey
      in: query
      name: key
      description: API key in the `?key=` query param. Accepted by the header-less PBX endpoint GET /api/v1/cid/{number} and by the webhook adapters POST /api/v1/integrations/retell/inbound, POST /api/v1/integrations/vapi/tool, and POST /api/v1/sbc/redirect, whose upstream platforms set only a static webhook URL and cannot send an Authorization/X-API-Key header. The key can leak into access logs — use a dedicated, rotated key, and prefer header auth wherever the client supports it.