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

Contents of this page

General Requirements
Actions
- Request Details About a Phone Number
Get Started with Add-ons
Example
Country Codes and Dialing Codes
Phone Number Cleansing Codes
Phone Type Codes
Time Zones

General Requirements

Request Requirements

Authentication: Basic (easiest to implement) or Digest
Endpoint: https://rest-ww.telesign.com/v1/phoneid/{complete_phone_number}
The phone number must include the country code.
Encoding: Accepts only UTF-8 unicode characters as inputs
MIME Type: application/json
Required Headers: Content-Type

Response Details

MIME Type: application/json

NOTE:

As long as you are not including the addons object in your request payload, you can also use the application/x-www-form-urlencoded MIME type in your request instead of application/json.

Actions

Request Details About a Phone Number

Request information about a phone number including phone type, telecom carrier, and location information.

For quick instructions about how to send your first request using this action, see Request Details About a Phone Number.

For full technical details of this action, including available parameters, see the PhoneID Request (POST /phoneid) reference page.

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 device details, portin history, subscriber contact information, and more. For complete details on what add-ons are available, see Get Started with Add-ons.

Example

This example demonstates basic usage of the PhoneID API. See Get Started with Add-ons for examples that include add-ons.

Request

application/json

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/json

{
  "account_lifecycle_event": "create",
  "originating_ip": "203.0.113.45"
}

Response (body only)

application/json

{
   "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 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

Check out these related pages:

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