Want to provide feedback?

Write to docs@telesign.com.

Request Details About a Phone Number

Use this action to get information such as phone type, telecom carrier name, and location for a given phone number. To send your first request, try out the PhoneID API Explorer below. You can also get a code snippet for the request in the language of your choice.

Reference Page

POST /phoneid/{complete_phone_number}

See full technical details for this API, including definitions for all parameters.

Contents of this page

Try It

If you have been granted access and credentials for the PhoneID API, you can try a test request in the API Explorer below. You can also get a code snippet for the request.

  1. Click the Auth tab and for Username add your customer ID. For Password add your API key.
  2. In the Settings tab, for the complete_phone_number field, enter the complete phone number that you want to request information about (include the country code).
  3. Click Send.
  4. Click the Code Generation tab and use the Language and Library menus to choose the language you want your code snippet in.

Congratulations! You’ve sent your first request for details about a phone number using TeleSign’s PhoneID API and generated a code snippet.

Full technical details for this action, including all available parameters for requests, can be found at POST /phoneid/{complete_phone_number}.

PhoneID API Explorer
When using this API Explorer, you will be charged your contracted rate for each transaction. The time shown is not indicative of regular transmission rates, and only applies to this API Explorer.
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
complete_phone_number
$$.env
No $$.env variables are being used in this request.

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

Examples

Here is an example of the basic usage of this action:

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

Next Steps

Check out these related pages: