Phone ID Live Status - Request status info for a number

📘

NOTE:

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

This page walks you step-by-step through sending your first request for status information about a phone number using Telesign Phone ID Live Status. These instructions make use of the API Explorer widget in the Reference section, so you don't have to write any code. You can also get a code snippet for the request in the language of your choice.

Before you begin, make sure Telesign has granted you access to this specific product and given you access credentials (Customer ID and API key). If you need help with either of those items, contact our Customer Support Team.

🚧

CAUTION:

Sending too many request 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.

Use these instructions with the API Explorer to send a request for status information about a specific phone number and get a code snippet for making the request in the language of your choice.

1. Click the Auth tab and for Username add your Customer ID. For Password add your API key.
2. Click the Settings tab and in the complete_phone_number field, enter your phone number with the country code. Do not include special characters or spaces.
3. Click Send.
4. Click the Code Generation tab and use the Language and Library drop-downs to choose the language you want your code snippet in.

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

For a full description of all available parameters, see GET /v1/phoneid/live/{complete_phone_number}.

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": "Marina del Rey",
      "state": "CA",
      "zip": "90292",
      "metro_code": "4480",
      "county": "Los Angeles",
      "country": {
         "name": "United States",
         "iso2": "US",
         "iso3": "USA"
      },
      "coordinates": {
         "latitude": 34.18264,
         "longitude": -118.30840
      },
      "time_zone": {
         "name": "America/Los_Angeles",
         "utc_offset_min": "-8",
         "utc_offset_max": "-8"
      }
   },
   "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
   }
}