Want to provide feedback?

Write to docs@telesign.com.

Get Started with the PhoneID Live API

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

This page provides instructions and references for features of the PhoneID Live API.


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

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

General Information

All requests submitted for the PhoneID Live API:

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Use https://rest-ww.telesign.com/v1/phoneid/live/{complete_phone_number} as the base endpoint
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type application/x-www-form-urlencoded in request headers

Request Status Info for a Number

For quick instructions about how to send your first request for status information about a phone number, see the Request Status Info for a Number page.

You can read the API reference page and see available parameters on the GET /phoneid/live page.

PhoneID Live API Examples

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


Example Request
GET https://rest-ww.telesign.com/v1/phoneid/live/15555551234?ucid=BACS HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
Host: rest-ww.telesign.com


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

Next Steps

This section provides suggestions for next steps to take.