PhoneID Live API - Request Status Info for a Number

This page walks you step-by-step through sending your first request for status information about a phone number using the TeleSign PhoneID Live API. These instructions make use of the API Explorer widget in the Reference section, so you don't have to write any code. You can also get a code snippet for the request in the language of your choice.

Before you begin, make sure TeleSign has granted you access to this specific API and given you access credentials (Customer ID and API key). If you need help with either of those items, contact our Customer Support Team.



Sending too many request to the API for the same phone number within a short period of time may result in an error, even if data is available for that number. If you receive a -60001 error in the response after making consecutive requests for the same phone number, consider limiting your request rate.

Use these instructions with the PhoneID Live Explorer 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 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!

For a full description of all available parameters, see GET /v1/phoneid/live/{complete_phone_number}.

PhoneID Live Information

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Use{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


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


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

Did this page help you?