openapi: 3.1.0
info:
  title: Global Telephone Number Location Finder API
  description: >
    This API provides location and related information for telephone numbers worldwide using extensive global telephony data and advanced lookup techniques.

    To use this API, you need an API key. Register for an API key at [Interzoid Registration](https://www.interzoid.com/register-api-account).

    For more information about this API, visit the [Global Telephone Number Location Finder API Documentation](https://www.interzoid.com/apis/global-telephone-info).

    You can also try this API [interactively](https://try.interzoid.com) or in high-speed [batch mode](https://batch.interzoid.com).
  version: 1.0.0
  contact:
    name: Interzoid Support
    url: https://www.interzoid.com
    email: support@interzoid.com
externalDocs:
  description: API home page and documentation
  url: https://www.interzoid.com/apis/global-telephone-info
servers:
  - url: https://api.interzoid.com
    description: Production server
tags:
  - name: Global Phone Number Info
    description: Retrieves location and related details for telephone numbers across the globe.
paths:
  /getglobalphoneinfo:
    get:
      operationId: getGlobalPhoneInfo
      tags:
        - Global Phone Number Info
      summary: Retrieve Telephone Number Location Information
      description: >
        Returns location details such as country, city, and organization for a given telephone number. Include your API key (license) in the request. Register for an API key at https://www.interzoid.com/register-api-account.
      parameters:
        - name: license
          in: query
          required: true
          description: >
            Your API license key. Register for an API key at
            [Interzoid Registration](https://www.interzoid.com/register-api-account).
          schema:
            type: string
          examples:
            license:
              summary: API Key Example
              value: "fh5hs7*****"
        - name: number
          in: query
          required: true
          description: The telephone number to look up (include country code, e.g., +4906979550).
          schema:
            type: string
          examples:
            phoneNumber:
              summary: Telephone Number Example
              value: "+4906979550"
      responses:
        '200':
          description: Successful response containing telephone number location information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Country:
                    type: string
                    description: The country associated with the telephone number.
                  Locale:
                    type: string
                    description: The region or state within the country.
                  City:
                    type: string
                    description: The city associated with the telephone number.
                  Organization:
                    type: string
                    description: The organization or service provider linked to the number.
                  Code:
                    type: string
                    description: Response code, "Success" if the call is successful.
                  Credits:
                    type: integer
                    description: Remaining credits for your API license.
              examples:
                success:
                  value:
                    Country: "Germany"
                    Locale: "Lower Saxony"
                    City: "Hanover"
                    Organization: "Frankfurt Marriott Reservations"
                    Code: "Success"
                    Credits: 19997878
        '400':
          description: Bad request (e.g., missing or invalid parameters).
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Invalid license key or telephone number missing."
        '402':
          description: API key not found.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "API key not found."
        '403':
          description: Insufficient API credits remaining.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Insufficient API credits remaining."
        '405':
          description: Method not allowed.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Method not allowed."
        '429':
          description: Rate limits reached.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Rate limits reached."
        '500':
          description: Internal server error.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Internal server error."
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: license
      in: query
  schemas: {}
security:
  - apiKeyAuth: []