Get Started with the PhoneID Live API

The PhoneID Live API 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 the PhoneID Live API.

NOTE:

The PhoneID Live response also includes the information returned by the PhoneID API.

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 API on 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 PhoneID Live API transaction.

Request

Phone ID Live Request
HTTPS
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 Response
HTTPS
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
   }
}

Next Steps

Check out these related pages: