openapi: 3.1.0
info:
  title: numlookupapi
  version: "1"
  summary: Real-time phone number validation with carrier and location lookup.
  description: >-
    numlookupapi validates phone numbers and returns their formatting, country,
    location, carrier and line type. All endpoints are served over HTTPS and
    return JSON. Authenticate every request with your API key, either as the
    `apikey` query parameter or the `apikey` request header.


    This document is generated from the numlookupapi service implementation and
    is the machine-readable source of truth for the v1 REST API. A human-readable
    version is available at https://numlookupapi.com/docs.
  contact:
    name: numlookupapi support
    email: support@numlookupapi.com
    url: https://support.numlookupapi.com/
  x-logo:
    url: https://numlookupapi.com/numlookupapi_logo.svg
servers:
  - url: https://api.numlookupapi.com
    description: Production
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
tags:
  - name: Validation
    description: Phone number validation.
  - name: Metadata
    description: Account status.
paths:
  /v1/validate/{number}:
    get:
      tags:
        - Validation
      summary: Validate a phone number
      operationId: validateNumber
      description: >-
        Validates a phone number and returns its formatting, country, location,
        carrier and line type. Supply the number either with its country prefix
        (e.g. `+14158586273`) or without a prefix together with the
        `country_code` parameter. An unrecognised but well-formed number returns
        HTTP 200 with `valid: false`.
      parameters:
        - name: number
          in: path
          required: true
          description: >-
            The phone number to validate, either including the country prefix
            (`+14158586273`) or without a prefix when `country_code` is given.
          schema:
            type: string
          example: "+14158586273"
        - name: country_code
          in: query
          required: false
          description: >-
            ISO 3166-1 alpha-2 country code (e.g. `US`) for the number. When set,
            the country prefix does not need to be prepended to the number.
          schema:
            type: string
          example: "US"
      responses:
        '200':
          description: Validation result. Check the `valid` field.
          headers:
            X-RateLimit-Limit-Quota-Month:
              $ref: '#/components/headers/RateLimitLimitQuotaMonth'
            X-RateLimit-Remaining-Quota-Month:
              $ref: '#/components/headers/RateLimitRemainingQuotaMonth'
            X-Cost:
              $ref: '#/components/headers/Cost'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
              examples:
                valid:
                  summary: A valid number
                  value:
                    valid: true
                    number: "14158586273"
                    local_format: "4158586273"
                    international_format: "+14158586273"
                    country_prefix: "+1"
                    country_code: "US"
                    country_name: "United States of America"
                    location: "Novato"
                    carrier: "AT&T Mobility LLC"
                    line_type: "mobile"
                invalid:
                  summary: A well-formed but unrecognised number
                  value:
                    valid: false
                    number: "14158586273"
                    local_format: ""
                    international_format: ""
                    country_prefix: ""
                    country_code: ""
                    country_name: ""
                    location: ""
                    carrier: ""
                    line_type: "N/A"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /v1/status:
    get:
      tags:
        - Metadata
      summary: Account quota status
      operationId: getStatus
      description: >-
        Returns your current monthly and grace quota usage. Requests to this
        endpoint do not count against your quota or rate limit.
      responses:
        '200':
          description: Current quota usage for the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                account_id: 313373133731337
                quotas:
                  month:
                    total: 300
                    used: 72
                    remaining: 228
                  grace:
                    total: 0
                    used: 0
                    remaining: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key passed as the `apikey` query parameter.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: >-
        API key passed as the `apikey` request header. This is the recommended
        method as it keeps the key out of URLs and access logs.
  headers:
    RateLimitLimitQuotaMonth:
      description: Your monthly request quota.
      schema:
        type: integer
      example: 300
    RateLimitRemainingQuotaMonth:
      description: Remaining requests in your monthly quota.
      schema:
        type: integer
      example: 228
    Cost:
      description: >-
        Number of requests this call counted against your quota (0 for sandbox
        keys and non-counting endpoints).
      schema:
        type: integer
      example: 1
  responses:
    Unauthorized:
      description: >-
        An API key was supplied but is invalid. Anonymous access without a key
        is permitted on some plans; an invalid key is always rejected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: "If you specify an apikey it has to be a valid one."
    ValidationError:
      description: >-
        The request failed validation, e.g. an empty number or an invalid
        `country_code`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidCountryCode:
              value:
                message: "invalid_country_code"
                info: "For more information, see documentation: https://numlookupapi.com/docs/status-codes#_422"
            invalidNumber:
              value:
                message: "invalid_number"
                info: "For more information, see documentation: https://numlookupapi.com/docs/status-codes#_422"
    RateLimited:
      description: >-
        You have exceeded your monthly quota or minute rate limit. Only
        successful requests count against your quota.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: "You have reached your monthly limit, please upgrade your plan"
    ServerError:
      description: An unexpected error occurred on our side.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: "something went wrong"
            info: "For more information, see documentation: https://numlookupapi.com/docs/status-codes#_500"
  schemas:
    ValidationResult:
      type: object
      description: The result of validating a phone number.
      properties:
        valid:
          type: boolean
          description: Whether the number is a valid, recognised phone number.
          example: true
        number:
          type: string
          description: The cleaned number that was looked up (digits only).
          example: "14158586273"
        local_format:
          type: string
          description: The number in national/local format. Empty when invalid.
          example: "4158586273"
        international_format:
          type: string
          description: The number in international format. Empty when invalid.
          example: "+14158586273"
        country_prefix:
          type: string
          description: The international dialing prefix. Empty when invalid.
          example: "+1"
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code. Empty when invalid.
          example: "US"
        country_name:
          type: string
          description: Full country name. Empty when invalid.
          example: "United States of America"
        location:
          type: string
          description: Region or city associated with the number. May be empty.
          example: "Novato"
        carrier:
          type: string
          description: The carrier/operator for the number. May be empty.
          example: "AT&T Mobility LLC"
        line_type:
          type: string
          description: The type of phone line.
          enum:
            - landline
            - mobile
            - satellite
            - paging
            - special_services
            - premium_rate
            - toll_free
            - N/A
          example: "mobile"
      required:
        - valid
        - number
        - local_format
        - international_format
        - country_prefix
        - country_code
        - country_name
        - location
        - carrier
        - line_type
    StatusResponse:
      type: object
      properties:
        account_id:
          type: integer
          description: Your account (team) id. Absent for anonymous requests.
          example: 313373133731337
        quotas:
          type: object
          properties:
            month:
              $ref: '#/components/schemas/QuotaBucket'
            grace:
              $ref: '#/components/schemas/QuotaBucket'
          required:
            - month
      required:
        - quotas
    QuotaBucket:
      type: object
      properties:
        total:
          type: integer
          example: 300
        used:
          type: integer
          example: 72
        remaining:
          type: integer
          example: 228
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        info:
          type: string
          description: >-
            Link to the relevant documentation. Present on validation (422),
            server (500) and other errors raised by the application.
      required:
        - message
