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": null,
      "state": null,
      "zip": null,
      "metro_code": null,
      "county": null,
      "country": {
         "name": "United States",
         "iso2": "US",
         "iso3": "USA"
      },
      "coordinates": {
         "latitude": null,
         "longitude": null
      },
      "time_zone": {
         "name": null,
         "utc_offset_min": null,
         "utc_offset_max": null
      }
   },
   "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"
   }
}

What’s Next