Get Started with the PhoneID API

The PhoneID API is a REST API that provides a cleansed phone number, phone type, and telecom carrier information that can be used to determine which phone numbers are a potential fraud risk, and what the best communication method for a phone number is (voice, SMS).

The PhoneID web service is discussed in the following sections:

General Information

All requests submitted for the PhoneID API:

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Use https://rest-api.telesign.com/v1/phoneid/<complete_phone_number> as the base endpoint. The phone number must include the country code.
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type - application/x-www-form-urlencoded in request headers UNLESS YOU USE THE CONTACT ADD-ON. To use this add-on you must switch to use application/json as the content-type for this API. Learn more on the Get Started with the Contact Add-on page.

Request Details About a Phone Number

For quick instructions about how to send your first request for information about a phone number (information includes device-type, telecom carrier, and phone registration information), see the Request Details About a Number page.

For a list of available parameters, see the POST /phoneid page.

Get Started with the Contact Add-on

Add-ons are a feature of the PhoneID API that allow you to make multiple queries about a phone number in a single request. You can mix and match them to get detailed information about phone numbers, such as location, carrier, subscriber information, and more. For complete details on what add-ons are available, read the Get Started with the Contact Add-on page.

PhoneID API Examples

This section provides examples of the PhoneID API, implemented with application/x-www-form-urlencoded headers. If you want to use the Contact add-on, refer to the Get Started with the Contact Add-on page.

Here is an example POST request to the PhoneID API:

Example POST Request to PhoneID API
POST https://rest-api.telesign.com/v1/phoneid/15555551212 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 14:51:26 GMT
Content-Type: application/x-www-form-urlencoded

originating_ip=203.0.113.45&account_lifecycle_event=create

Here is an example POST response from the PhoneID API:

NOTE:

The phone number in the example is for display only.

Example POST Response
{
   "reference_id": "F0123456789ABCDEF0123456789ABCDE",
   "status": {
      "updated_on": "2015-10-03T14:51:28.709526Z",
      "code": 300,
      "description": "Transaction successfully completed"
   },
   "location": {
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90066",
      "metro_code": "4480",
      "county": "Los Angeles County",
      "country": {
         "name": "United States",
         "iso2": "US",
         "iso3": "USA"
      },
      "coordinates": {
         "latitude": 33.99791,
         "longitude": -118.42302
      },
      "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": "1",
      "description": "FIXED_LINE"
   },
   "blocklisting": {
     "block_code": 0,
     "block_description": "Not blocked",
     "blocked": False
   },  
   "carrier": {
      "name": "Verizon"
   }
}

Country Codes and Dialing Codes

If you need to know country and dialing codes, review the Country Codes and Dialing Codes section of the Codes, Languages, and Time Zones page.

Phone Number Cleansing Codes

Phone number cleansing codes indicate how a phone number you submitted was cleansed before use. You can see a complete list of these codes in the Phone Number Cleansing Codes section of the Codes, Languages, and Time Zones page.

Phone Type Codes

Phone type codes describe what kind of phone is associated with the phone number you provide. You can see a complete list of these codes in the Phone Type Codes section of the Codes, Languages, and Time Zones page.

Next Steps

This section offers some suggestions for next steps to take.

  • Request Details About a Number - Learn how to send your first request for details about a phone number.
  • Get Started with the Contact Add-on - Try an add-on for the PhoneID API. The contact add on lets you retrieve the name and address associated with the phone number you submit, without requesting explicit consent from your end user.