api-ninjas-com Validate Phone API

openapi: 3.2.0
info:
  title: Ninjas Validate Phone API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Validate Phone
  description: The Validate Phone API allows you to check whether a given phone number is valid and return its metadata.
paths:
  /v1/validatephone:
    get:
      tags:
      - Validate Phone
      summary: Validate a phone number and get its metadata
      description: Validates a phone `number` and returns its normalised format, country and location. For carrier and line type use /phonelookup.
      operationId: validatePhone
      parameters:
      - $ref: '#/components/parameters/ValidatePhoneOpenapi_number'
      - $ref: '#/components/parameters/ValidatePhoneOpenapi_country'
      responses:
        '200':
          description: Successful response with phone number metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatePhoneResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatePhoneOpenapi_ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatePhoneOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatePhoneOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    ValidatePhoneOpenapi_ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message describing the failure.
    ValidatePhoneResponse:
      type: object
      properties:
        is_valid:
          type: boolean
          description: Indicates if the phone number is valid.
        is_formatted_properly:
          type: boolean
          description: Indicates if the phone number is formatted properly.
        country:
          type: string
          description: The country where the phone number is registered.
        location:
          type: string
          description: The specific location within the country.
        timezones:
          type: array
          items:
            type: string
          description: List of timezones applicable to the phone number.
        format_national:
          type: string
          description: The phone number formatted in national style.
        format_international:
          type: string
          description: The phone number formatted in international style.
        format_e164:
          type: string
          description: The phone number formatted according to E164 standard.
        country_code:
          type: integer
          description: The international country code of the phone number.
        line_type:
          type: string
          description: 'Line type of the number: mobile, landline, voip, toll_free, fixed_line_or_mobile, premium_rate, shared_cost, personal_number, pager, uan, voicemail, or unknown.'
        is_mobile:
          type: boolean
          description: Whether the number is a mobile (or fixed-line-or-mobile) number.
        format_rfc3966:
          type: string
          description: 'The phone number formatted as an RFC3966 tel: URI.'
        is_possible:
          type: boolean
          description: Whether the number is a possible number (valid length/pattern), even if not confirmed valid.
  parameters:
    ValidatePhoneOpenapi_number:
      name: number
      in: query
      description: Phone number to check. The leading '+' is optional. If country is not set, include the country code (e.g. 12065550100 or +12065550100).
      required: true
      schema:
        type: string
    ValidatePhoneOpenapi_country:
      name: country
      in: query
      description: 2-letter ISO-3166 country code the phone number belongs to.
      required: false
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api