Request Details About a Number

You can find out information such as device-type, telecom carrier name and phone registration information using the PhoneID API. To send your first request for information, try out the PhoneID API Explorer below. If you have your credentials, follow the instructions to use TeleSign’s PhoneID API for the first time. You will also be able to get a code snippet for the request in the language of your choice.


The explorer is set up for use with Content-Type application/x-www-form-urlencoded. If you want to use add-ons, Content-Type should be application/json. Refer to the Get Started with Add-ons page for more information.

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

Use these instructions with the PhoneID API Explorer (above) to request details about a phone number.

  1. Click the Auth [basic] tab and for Username add your customer ID. For Password add your API key.
  2. Click the Variables tab and in the complete_phone_number field, enter the complete phone number, including the country code, that you want to request information about. (See available parameters on the API reference page - POST v1/phoneid.)
  3. Click Send.
  4. Click the Code Generation tab and use the Language and Library drop-downs 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!

You can see more about available parameters for requests on the PhoneID Request (POST /phoneid) page.

The rest of this page provides additional details about TeleSign’s PhoneID API.

PhoneID API Information

All requests submitted for the PhoneID API:

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Use<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 THE CONTACT ADD-ON. To use this add-on you must switch to use application/json as the content-type for this API. Learn more on the Get Started with the Contact Add-on page.


Here is an example POST request to the PhoneID API:

POST Request to PhoneID API
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


Here is an example POST response from the PhoneID API:

POST Response from PhoneID API
   "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

This section offers some suggestions for next steps to take.

  • Check out another product -
  • Get Started with the Contact Add-on - Try out the Contact add-on with PhoneID. The Contact add-on lets you retrieve details associated with the phone number you submit in your request. Details include name, street address, city, state or province, zip code and email.