Phone ID Live Status - Request status info for a number

~CAUTION: This page is hidden because it needs to be rewritten - it currently is limited to discussing API Explorer. Saving this page for later use for a new how-to-page. 9/11/23.~

📘
NOTE:
To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page explains how to send your first request for status information about a specific phone number using Telesign Phone ID Live Status directly from our docs site, without writing any code. These instructions make use of the API Explorer widget in the Reference section. You can also get a code snippet for the request in the language of your choice.

Before you begin

Ensure that you have the following:

Access to Phone ID Live Status: Make sure Telesign has granted you access to this specific product. If you don't have access, contact our Customer Support Team.
Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.

Steps

🚧
CAUTION:
Using your account credentials in the API Explorer to make a request results in your account being charged for the transaction.
You are subject to all compliance rules as appropriate for your transaction.

Open the reference page for the GET /v1/phoneid/live/{complete_phone_number} endpoint.
Under the AUTHENTICATION header in the right panel of the page, put your Customer ID in the Customer ID field and your API key in the API Key field.
Go to the PATH PARAMS section in the middle panel of the page. For the complete_phone_number field, enter your test phone number with the country code. Do not include special characters or spaces. For a full description of all available parameters, see GET /v1/phoneid/live/{complete_phone_number}.
Select Try It! in the right panel to send your request to Telesign. You will be charged the standard rate for this transaction.
🚧
CAUTION:
Sending too many requests to the API for the same phone number within a short period of time may result in an error, even if data is available for that number. If you receive a -60001 error in the response after making consecutive requests for the same phone number, consider limiting your request rate.
You can also select the copy icon to the left of Try It! to copy the code snippet displayed. To change the programming language of the snippet, select one of the options under the LANGUAGE header in the right sidebar.

Congratulations! You've sent your first request for status information using Phone ID Live Status and generated a code snippet!

General Requirements

Authentication: Basic (easiest to implement) and Digest
Endpoint: https://rest-ww.telesign.com/v1/phoneid/live/{complete_phone_number}
Encoding: Accepts only UTF-8 encoded unicode characters as inputs
Required headers: Use Content-Type - application/x-www-form-urlencoded

Examples

This section provides an example of a typical request and response for Phone ID Live Status.

Request

Example request

GET https://rest-ww.telesign.com/v1/phoneid/live/15555551234?ucid=BACS HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com

Response

After receiving and processing the request message, the Telesign web server fulfills the service request by responding with an HTTP response message. Notice that the response message begins with a status-line followed by the general, response, and entity headers.

The response message contains a payload: the message body used to deliver the product served by this web service (the results of the service request). In this case, it’s the Operational State of the phone number, in addition to the Standard Information Set for the phone number. Note that the information is structured into an industry-standard JSON dictionary (a collection of objects composed of name/value pairs).

Example response

HTTP/1.1 200 OK
Date: Wed, 03 Oct 2015 21:51:28 GMT
Server: CERN/3.0 libwww/2.17
Content-Length: 1242
Allow: GET,HEAD
Content-Type: application/json

{
   "reference_id": "0123456789ABCDEF0123456789ABCDEF",
   "sub_resource": "live",
   "status": {
      "updated_on": "2015-10-03T21:51:28.709526Z",
      "code": 300,
      "description": "Transaction successfully completed"
   },
   "errors": [],
   "location": {
      "city": "Odessa",
      "state": "TX",
      "zip": "79758",
      "metro_code": "36220",
      "county": "Ector",
      "country": {
         "name": "United States",
         "iso2": "US",
         "iso3": "USA"
      },
      "coordinates": {
         "latitude": 31.8466,
         "longitude": -102.36778
      },
      "time_zone": {
         "name": "America/Chicago",
         "utc_offset_min": "-6",
         "utc_offset_max": "-6"
      }
   },
   "numbering": {
      "original": {
         "complete_phone_number": "15555551234",
         "country_code": "1",
         "phone_number": "5555551234"
      },
      "cleansing": {
         "call": {
            "country_code": "1",
            "phone_number": "5555551234",
            "cleansed_code": 100,
            "min_length": 10,
            "max_length": 10
         },
         "sms": {
            "country_code": "1",
            "phone_number": "5555551234",
            "cleansed_code": 100,
            "min_length": 10,
            "max_length": 10
         }
      }
   },
   "phone_type": {
      "code": "2",
      "description": "MOBILE"
   },
   "carrier": {
      "name": "Verizon"
   },
   "live": {
      "subscriber_status": "ACTIVE",
      "device_status": "REACHABLE",
      "roaming": "NO",
      "roaming_country": null,
      "roaming_country_iso2": null
   }
}