Phone ID - Get started

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

Reference pages

General requirements

Request requirements

  • Authentication: Basic (easiest to implement) or Digest
  • Endpoint: https://rest-ww.telesign.com/v1/phoneid/{complete_phone_number} or https://rest-ww.telesign.com/v1/phoneid
  • 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 information about a phone number including phone type, telecom carrier, and location information; the phone number is specified in the path.

Request information about a phone number including phone type, telecom carrier, and location information; the phone number is specified in the request body.

Example

Request

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)

{
   "reference_id": "F0123456789ABCDEF0123456789ABCDE",
   "status": {
      "updated_on": "2015-10-03T14:51:28.709526Z",
      "code": 300,
      "description": "Transaction successfully completed"
   },
   "location": {
      "city": "Odessa",
      "state": "TX",
      "zip": "79758",
      "metro_code": "36220",
       "county": "Ector",
      "country": {
         "name": "United States",
         "iso2": "US",
         "iso3": "USA"
      },
      "coordinates": {
         "latitude": 31.8466,
         "longitude": -102.36778
      },
      "time_zone": {
         "name": "America/Chicago",
         "utc_offset_max": "-6",
         "utc_offset_min": "-6"
      }
   },
   "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"
   }
}