PhoneID Live API Overview

The PhoneID Live API delivers insights such as whether a phone is active or disconnected, a device is reachable or unreachable and its 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

The information returned by PhoneID Live includes the information returned by PhoneID.

The PhoneID Live web service is discussed in the following sections:


PhoneID Live coverage is as follows:

  • 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)


The PhoneID Live web service is exposed with a URI of the form.[complete_phone_number]?ucid=[use_case_code]


The PhoneID Contact API supports the following:

  • Authentication - Basic (easiest to implement) and Digest Authentication
  • HTTP Methods -
    • GET - You can retrieve the results of the message you sent using the GET method. You do this by sending a GET request containing the reference id for the message you sent. TeleSign returns a response message in the form of a JSON object in the entity body.
  • Content-Type - application/x-www-form-urlencoded

Request and Response Parameters

For a complete list of request and response parameters, refer to:

PhoneID Live API Examples

This section contains an example of a typical request-response transaction for the PhoneID Live web service.


The following REST code block is an example of a request sent to the /v1/phoneid/live/subresource. Note that a complete phone number is sent as a subresource identifier, and that the use case is sent as a query parameter.

Example Request
Accept-Encoding: gzip,deflate
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
User-Agent: CERN-LineMode/2.15 libwww/2.17b3


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 Message
HTTP/1.1 200 OK
Date: Wed, 03 Oct 2015 21:51:28 GMT
Server: CERN/3.0 libwww/2.17
Content-Length: 1242
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