8x8 Number Lookup API

openapi: 3.2.0
info:
  title: Number Lookup API
  version: '1'
  description: Number Lookup API allows customers to perform various levels of information lookup on a given phone number.
  contact:
    name: 8x8 Inc
    url: https://cpaas.8x8.com
    email: cpaas-support@8x8.com
  termsOfService: https://cpaas.8x8.com/sg/terms-and-conditions/
servers:
- url: https://lookup.8x8.com
  description: Asia-Pacific region
- url: https://lookup.us.8x8.com
  description: North America region
- url: https://lookup.8x8.id
  description: Europe region
- url: https://lookup.8x8.uk
  description: Indonesia region
security:
- apiKey: []
tags:
- name: Number Lookup API
paths:
  /api/v1/subaccounts/{subAccountId}/phones/{phoneNumber}:
    get:
      responses:
        '200':
          description: "* The response body contains the lookup information retrieved for the phone number.\n  * For lookup type `format`, the  response only returns static data about the number like phone type and country code. \n  * For lookup type `operator`, the response contains additional information like porting status and the current operator information. \n  * For lookup type `live`, the response includes detailed information like current handset and roaming status, and operator information for original, current and roaming operators.\n"
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    description: The unique identifier provided for each request.
                    example: cb4d95e9-002c-40f2-b230-ac85007004bd
                  phoneNumber:
                    type: string
                    description: 'Phone number in E.164 format. '
                    example: '15108675310'
                  phoneNumberNational:
                    type: string
                    description: Phone number in national format.
                    example: (510) 867-5310
                  phoneType:
                    type: string
                    description: 'Type of phone. Possible values are UAN, FixedLine, Mobile, FixedLineOrMobile, TollFree, PremiumRate, SharedCost, VoIP, PersonalNumber, Pager, Voicemail, Unknown. '
                    example: FixedLineOrMobile
                  country:
                    type: string
                    description: Two-letter country the phone number belongs to.
                    example: US
                  roaming:
                    type: boolean
                    description: Roaming status. `null` if unknown. Only avaialble for advanced query.
                    example: true
                  presence:
                    type: boolean
                    description: Latest handset status as recorded by the operator. `true` if switched on, `false` if switched off and `null` if unknown. Only available for advanced query.
                    example: true
                  ported:
                    type: boolean
                    example: false
                    description: Porting status. `true` if ported, `null` if unknown and `false` otherwise.
                  status:
                    $ref: '#/components/schemas/lookup-status'
                  currentOperator:
                    $ref: '#/components/schemas/network-lookup-data'
                  originalOperator:
                    $ref: '#/components/schemas/network-lookup-data'
                  roamingOperator:
                    $ref: '#/components/schemas/network-lookup-data'
              examples:
                response:
                  value:
                    requestId: c01982ec-64ee-4bed-a414-ac8500745b9a
                    phoneNumber: '+15108675310'
                    phoneNumberNational: (510) 867-5310
                    phoneType: FixedLineOrMobile
                    country: US
                    roaming: true
                    presence: true
                    status:
                      state: ok
                      timestamp: '2020-12-04T05:52:51.20Z'
                    originalOperator:
                      operatorName: Sprint-Nextel
                      mcc: '310'
                      mnc: '120'
                      country: US
                    roamingOperator:
                      operatorName: Verizon Wireless
                      mcc: '310'
                      mnc: '590'
                      country: US
                    ported: false
                    currentOperator:
                      operatorName: Verizon Wireless
                      mcc: '310'
                      mnc: '590'
                      country: US
            error-response:
              examples:
                response:
                  value:
                    roaming: null
                    presence: null
                    originalOperator:
                      operatorName: PT Indonesian Satellite Corporation Tbk (INDOSAT)
                      mcc: '510'
                      mnc: '21'
                      country: ID
                    roamingOperator: null
                    ported: null
                    currentOperator:
                      operatorName: PT Indonesian Satellite Corporation Tbk (INDOSAT)
                      mcc: '510'
                      mnc: '21'
                      country: ID
                    requestId: 5611682f-4ecb-4c62-b685-ac8a0101abe9
                    phoneNumber: '+6285611111111'
                    phoneNumberNational: 0856-1111-1111
                    phoneType: Mobile
                    country: ID
                    status:
                      state: error
                      timestamp: '2020-12-07T07:38:11.43Z'
                      errorCode: 6000
                      errorMessage: Destination operator is currently not available
        '400':
          description: Bad request error response
          content:
            application/json:
              schema:
                title: ErrorResponse
                required:
                - code
                - errorId
                - timestamp
                type: object
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error description
                  errorId:
                    type: string
                    description: Unique id of error. You can use it as reference when sending enquiries to 8x8 support
                    format: uuid
                  timestamp:
                    type: string
                    description: Data and time of the error occurence
                    format: date-time
                description: Response in case of error
                example:
                  code: 1001
                  message: Provided subAccountId doesn't belongs to your account
                  errorId: 91b106f0-c0da-4aba-a43a-7af9c5893a80
                  timestamp: '2017-04-19T02:31:19.4297387+00:00'
              example:
                code: 1002
                message: Invalid MSISDN format (not E.164 international number)
                errorId: b4478860-b76c-e811-814e-022a35cc1c71
                timestamp: '2018-08-04T09:25:40.9235752+00:00'
        '401':
          description: Request was not authenticated response
          content:
            application/json:
              schema:
                $ref: '#/paths/~1api~1v1~1subaccounts~1%7BsubAccountId%7D~1phones~1%7BphoneNumber%7D/get/responses/400/content/application~1json/schema'
              example:
                code: 1200
                message: Request was not authenticated properly
                errorId: db9dced4-3534-4d86-9d18-6b448af0d621
                timestamp: '2018-08-02T09:42:38.8988997+00:00'
      summary: Get phone number lookup data
      parameters:
      - name: subAccountId
        in: path
        description: You must replace *{subAccountId}* with the subaccountid that you want to use. By default this is generated once you signed up with a new account at [https://connect.8x8.com](https://connect.8x8.com).
        required: true
        schema:
          maxLength: 50
          minLength: 3
          pattern: ^[A-Za-z0-9\-._&]{3,50}$
          type: string
      - in: path
        name: phoneNumber
        required: true
        description: "The phone number (MSISDN) on which a lookup should be performed.\nThe phone number can be entered in local or international format. \n\t- If local format is used, make sure to provide the country code in the query parameters."
        schema:
          type: string
      - in: query
        name: country
        description: Two-letter country code. If the phone number is in a national format, country is required.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - in: query
        name: type
        description: Lookup type. For basic information about the number format like country code you can set this to `format` (default). For operator information, set the type to `operator` and for detailed information on the current handset status, set this value to `live`. See description at the top of this page for more information.
        schema:
          type: string
          enum:
          - format
          - operator
          - live
      security:
      - apiKey: []
      description: "* Sending a **GET** request on this endpoint allows retrieving information about a phone number\n* 3 phone number lookup types are available with this endpoint:\n  1. `format`: identifies the phone number country and type (mobile, landline, etc..) and returns the number in E.164 format.\n  2. `operator`: retrieves information about the current mobile operator associated to the number. The information comes from 8x8 mobile number portability data. The object returned also includes the \"Format\" information described in (1).\n  3. `live`: performs a live lookup to retrieve the current roaming and presence status of a number. The objet returned also includes the \"Format\" and \"Operator\" information from  (1) and (2).\n\n* `format` lookup requests are **free of charge**, but `operator` and `live` lookup requests are paid.  \n* `operator` and `live` lookups are only available upon request. To get access to these lookup types, contact your account manager.\n\n\n## URL\n\n`https://lookup.8x8.com/api/v1/subaccounts/{subAccountID}/phones/{phoneNumber}`\n\n> *You must replace `{subAccountID}` in the URL above with the subacccount for which the lookup service was provisioned.*\n\n> *You must replace `{phoneNumber}` in the URL above with the phone number you wish to perform a lookup on.*"
      operationId: phone-number-lookup
      tags:
      - Number Lookup API
components:
  schemas:
    lookup-status:
      type: object
      title: Lookup status
      description: The status of the lookup request
      properties:
        state:
          type: string
          enum:
          - ok
          - error
          description: The state of lookup request. Could be "ok" or "error"
        detail:
          type: string
          description: Optional. Additional details for the status.
        timestamp:
          type: string
          format: date-time
          description: The current status timestamp
        errorCode:
          type: integer
          description: "Could have one of the following values:\n* **2000** - Internal error / Unknown provider error\n* **2004** - Provider timeout\n* **2005** - Provider error\n* **6000** - Live lookup on destination operator is currently not available\n* **6001** - SIM card is offline\n* **6002** - Mobile subscriber not reachable\n* **6003** - SIM card is deactivated\n* **6004** - Routing error\n* **6005** - SIM card is full\n        "
        errorMessage:
          type: string
          description: Human-readable error message text
      required:
      - state
      - timestamp
    network-lookup-data:
      type: object
      title: Operator Information
      properties:
        operatorName:
          type: string
          description: Name of the operator.
          example: Sprint-Nextel
        mcc:
          type: string
          description: Mobile country code.
          example: '310'
        mnc:
          type: string
          description: Mobile network code.
          example: '120'
        country:
          type: string
          description: Two-letter country code.
          example: US
      description: Model containing information about the operator.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '* 8x8 SMS API accepts an **ApiKey Bearer Token** authentication method.


        * You can generate  tokens from your customer portal  [https://connect.8x8.com/](https://connect.8x8.com/)


        * You need to include the following header in your requests: `Authorization: Bearer {apiKey}`


        > **Note**: Replace the `{apiKey}` placeholder with the key generated from the customer portal.

        ---

        If you haven''t created your account yet, please go to 8x8 website [https://connect.8x8.com](https://connect.8x8.com) to sign up.

        '