Get phone number lookup data

GET https://lookup.8x8.com/api/v1/subaccounts/:subAccountId/phones/:phoneNumber

Sending a GET request on this endpoint allows retrieving information about a phone number
3 phone number lookup types are available with this endpoint:
1. format: identifies the phone number country and type (mobile, landline, etc..) and returns the number in E.164 format.
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).
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).
format lookup requests are free of charge, but operator and live lookup requests are paid.
operator and live lookups are only available upon request. To get access to these lookup types, contact your account manager.

URL

https://lookup.8x8.com/api/v1/subaccounts/{subAccountID}/phones/{phoneNumber}

You must replace {subAccountID} in the URL above with the subacccount for which the lookup service was provisioned.

You must replace {phoneNumber} in the URL above with the phone number you wish to perform a lookup on.

Request

Path Parameters

subAccountId stringrequired

Possible values: >= 3 characters and <= 50 characters, Value must match regular expression ^[A-Za-z0-9\-._&]{3,50}$

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.

phoneNumber stringrequired

The phone number (MSISDN) on which a lookup should be performed. The phone number can be entered in local or international format. - If local format is used, make sure to provide the country code in the query parameters.

Query Parameters

country string

Possible values: >= 2 characters and <= 2 characters

Two-letter country code. If the phone number is in a national format, country is required.

type string

Possible values: [format, operator, live]

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.

The response body contains the lookup information retrieved for the phone number.
- For lookup type format, the response only returns static data about the number like phone type and country code.
- For lookup type operator, the response contains additional information like porting status and the current operator information.
- For lookup type live, the response includes detailed information like current handset and roaming status, and operator information for original, current and roaming operators.

Schema

requestIdstring

The unique identifier provided for each request.

Example: cb4d95e9-002c-40f2-b230-ac85007004bd

phoneNumberstring

Phone number in E.164 format.

Example: 15108675310

phoneNumberNationalstring

Phone number in national format.

Example: (510) 867-5310

phoneTypestring

Type of phone. Possible values are UAN, FixedLine, Mobile, FixedLineOrMobile, TollFree, PremiumRate, SharedCost, VoIP, PersonalNumber, Pager, Voicemail, Unknown.

Example: FixedLineOrMobile

countrystring

Two-letter country the phone number belongs to.

Example: US

roamingboolean

Roaming status. null if unknown. Only avaialble for advanced query.

Example: true

presenceboolean

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

portedboolean

Porting status. true if ported, null if unknown and false otherwise.

Example: false

status object

The status of the lookup request

statestringrequired

The state of lookup request. Could be "ok" or "error"

Possible values: [ok, error]

detailstring

Optional. Additional details for the status.

timestampstring<date-time>required

The current status timestamp

errorCodeinteger

Could have one of the following values:

2000 - Internal error / Unknown provider error
2004 - Provider timeout
2005 - Provider error
6000 - Live lookup on destination operator is currently not available
6001 - SIM card is offline
6002 - Mobile subscriber not reachable
6003 - SIM card is deactivated
6004 - Routing error
6005 - SIM card is full

errorMessagestring

Human-readable error message text

currentOperator object

Model containing information about the operator.

operatorNamestring

Name of the operator.

Example: Sprint-Nextel

mccstring

Mobile country code.

Example: 310

mncstring

Mobile network code.

Example: 120

countrystring

Two-letter country code.

Example: US

originalOperator object

Model containing information about the operator.

operatorNamestring

Name of the operator.

Example: Sprint-Nextel

mccstring

Mobile country code.

Example: 310

mncstring

Mobile network code.

Example: 120

countrystring

Two-letter country code.

Example: US

roamingOperator object

Model containing information about the operator.

operatorNamestring

Name of the operator.

Example: Sprint-Nextel

mccstring

Mobile country code.

Example: 310

mncstring

Mobile network code.

Example: 120

countrystring

Two-letter country code.

Example: US

{
"requestId":"cb4d95e9-002c-40f2-b230-ac85007004bd",
"phoneNumber":"15108675310",
"phoneNumberNational":"(510) 867-5310",
"phoneType":"FixedLineOrMobile",
"country":"US",
"roaming":true,
"presence":true,
"ported":false,
"status":{
"state":"ok",
"detail":"string",
"timestamp":"2024-07-29T15:51:28.071Z",
"errorCode":0,
"errorMessage":"string"
},
"currentOperator":{
"operatorName":"Sprint-Nextel",
"mcc":"310",
"mnc":"120",
"country":"US"
},
"originalOperator":{
"operatorName":"Sprint-Nextel",
"mcc":"310",
"mnc":"120",
"country":"US"
},
"roamingOperator":{
"operatorName":"Sprint-Nextel",
"mcc":"310",
"mnc":"120",
"country":"US"
}
}

{
"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"
}
}

Schema

{
  "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"
  }
}

Bad request error response

Schema

codeintegerrequired

Error code

messagestring

Error description

errorIdstring<uuid>required

Unique id of error. You can use it as reference when sending enquiries to 8x8 support

timestampstring<date-time>required

Data and time of the error occurence

{
"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"
}

{
"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"
}

Request was not authenticated response

Schema

codeintegerrequired

Error code

messagestring

Error description

errorIdstring<uuid>required

Unique id of error. You can use it as reference when sending enquiries to 8x8 support

timestampstring<date-time>required

Data and time of the error occurence

{
"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"
}

{
"code":1200,
"message":"Request was not authenticated properly",
"errorId":"db9dced4-3534-4d86-9d18-6b448af0d621",
"timestamp":"2018-08-02T09:42:38.8988997+00:00"
}

Source: https://developer.8x8.com/connect/reference/phone-number-lookup · 8x8 CPaaS Developer Docs. Synced for support deflection.

Stephen - 8x8 Technical Support Level 2

June 29, 2026 02:47

0 Comments

Please sign in to leave a comment.

Get phone number lookup data

URL

Request

Path Parameters

Query Parameters

Schema

status object

currentOperator object

originalOperator object

roamingOperator object

Schema

Schema

Schema

0 Comments

Didn't find what you were looking for?