Phone ID Live Status - Get started

📘

NOTE:

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

Phone ID Live Status delivers insights such as whether a phone number is active or disconnected, whether its associated device is reachable or unreachable, and its associated device's roaming status. You can use it to find out:

• if the line is in service
• if the number is reachable
• if the mobile phone is roaming, and if so, in which country

This page provides instructions and references for features of Phone ID Live Status.

📘

NOTE:

The Phone ID Live Status response also includes basic Phone ID data.

Coverage

Phone ID Live Status is available for mobile in most countries. It is also available for landline in certain geographical markets. Please contact our Customer Support Team for additional information on availability for your intended markets.

General requirements

• Base URL: rest-ww.telesign.com
• Protocols: https
• Authentication: Basic (easiest to implement) or Digest
• Encoding: Accepts only UTF-8 unicode characters as inputs.
• Accepts: application/x-www-form-urlencoded
• Responds With: application/json
• Required Headers: Content-Type - application/x-www-form-urlencoded

Request status info for a number

Learn how to send your first request for status information about a phone number using this product on Phone ID Live Status - Try it without code.

Find complete reference info, including all available parameters on GET /v1/phoneid/live/{complete_phone_number}.

Example

Below is an example of a typical request and response for a Phone ID Live Status transaction.

Request

Phone ID Live Status Request

GET /v1/phoneid/live/15555551234?ucid=BACS HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded
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).

Phone ID Live Status Response

HTTP/1.1 200 OK
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
   }
}