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
Request Details About a Phone Number
Get Started with Add-ons
PhoneID API Examples
Country Codes and Dialing Codes
Phone Number Cleansing Codes
Phone Type Codes
Time Zones

General Information

All requests submitted for the PhoneID API:

Can be authenticated with Basic (easiest to implement) and Digest
Use https://rest-ww.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 ADD-ONS. To use add-ons you must switch to use application/json as the content-type for this API. Learn more on the Get Started with Add-ons 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 Phone Number page.

For a list of available parameters, see the PhoneID Request (POST /phoneid) page.

NOTE:

If you want to use PhoneID add-ons, refer to the Add-ons page. To use add-ons, you must implement with Content-Type application/json.

Get Started with Add-ons

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 Add-ons page.

NOTE:

To use PhoneID with add-ons you must implement the PhoneID API with Content-Type application/json, or they will not work.

PhoneID API Examples

This section provides examples of the PhoneID API, implemented with application/x-www-form-urlencoded. If you want to use add-ons, go to the Add-ons page for details. You cannot use add-ons with Content Type application/x-www-form-urlencoded.

POST Request and Response

Here is an example POST request to the PhoneID API:

Example POST Request to PhoneID API

POST https://rest-ww.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:

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 - example only",
         "country_code": "1",
         "phone_number": "5555551234 - example only"
      },
      "cleansing": {
         "call": {
            "country_code": "1",
            "phone_number": "5555551234 - example only",
            "cleansed_code": 100,
            "min_length": 10,
            "max_length": 10
         },
         "sms": {
            "country_code": "1",
            "phone_number": "5555551234 - example only",
            "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 on the Codes, Languages, and Time Zones page.

Phone Number Cleansing Codes

For a general list of phone number cleansing codes review the Phone Number Cleansing Codes section on the Codes, Languages, Time Zones page.

Phone Type Codes

For a general list of phone type codes review the Phone Type Codes section on the Codes, Languages, Time Zones page.

Time Zones

For a general list of time zones you can use review the Time Zones section on the Codes, Languages, Time Zones page.

Next Steps

This section offers some suggestions for next steps to take.

Request Details About a Phone Number - Learn how to retrieve details about a phone number such as phone type, carrier, phone owner details, and more.