Request Status Information for a Number

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 fastest way to send your first request for status information about a phone number is to try out TeleSign’s PhoneID Live API Explorer below. If you have your credentials, follow the instructions to use TeleSign’s PhoneID Live API for the first time. You will also be able to get a code snippet for the request in the language of your choice.

PhoneID Live API Explorer
NOTE: When using the PhoneID Live API Explorer, you will be charged your contracted rate for each transaction. The time shown in ms is not indicative of regular transmission rates, and only applies to the PhoneID Live API Explorer.
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
complete_phone_number
$$.env
No $$.env variables are being used in this request.

Use these instructions with the PhoneID Live Explorer (above) to send a request for status information about a specific phone number and get a code snippet for making the request in the language of your choice.

  1. Click the Auth [basic] tab and for **Username add your customer ID. For Password add your API key.
  2. Click the Settings tab and in the complete_phone_number field, enter your phone number with the country code. Do not include special characters or spaces.
  3. Click Send.
  4. Click the Code Generation tab and use the Language and Library drop-downs to choose the language you want your code snippet in.

Congratulations! You’ve sent your first request for status information using TeleSign’s PhoneID Live API and generated a code snippet!

You can see more about available parameters on the GET /phoneid/live.

The rest of this page details information about the PhoneID Live API. You can choose from these options:

PhoneID Live Information

  • 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

Examples

This section provides an example of a typical request and response for the PhoneID Live API.

Request

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

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

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
Allow: GET,HEAD
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.

  • GET /phoneid/live - Review the API reference for the PhoneID Live API.
  • Current Location Plus - Check out TeleSign’s newer product that is comparable to PhoneID Live. This add-on for the PhoneID API lets you retrieve latitude and longitude information for a phone number.