Phone ID Live Status - Get started

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

  • United Kingdom - Available for mobile and landline
  • United States - Available for mobile and landline in the 50 mainland states.
  • United States Territories - Available for mobile and landline in Puerto Rico, Guam, US Virgin Islands.
  • Canada - NOT AVAILABLE FOR MOBILE. In Canada, it is available for landlines.
  • Global - Available for mobile only (applying the exceptions specified above)

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 - Request status info for a number.

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

Did this page help you?