Get Started

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

Reference Page

POST /phoneid/{complete_phone_number}

The reference page provides full technical details for the API, including explanations of each request parameter and response property.

General Requirements

Request Requirements

  • Authentication: Basic (easiest to implement) or Digest
  • Endpoint:{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



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.


Request Details About a Phone Number

Reference Page: POST /phoneid/{complete_phone_number}

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

Try It

If you have credentials for TeleSign APIs, you can try a test request in the API Explorer. You can also get a code snippet for the request.

  1. Open the reference page for the POST /phoneid/{complete_phone_number} endpoint.
  2. Under the AUTHENTICATION header in the right panel of the page, put your Customer ID in the username field and your API key in the password field.
  3. Under the PATH PARAMS header in the middle panel of the page, enter the complete phone number (including country code) that you want information about in the complete_phone_number field. Do not include any special characters or spaces.
  4. Click Try It! in the right panel to see your transaction. You will be charged the standard rate for your transaction, and you are subject to all compliance rules as appropriate for your transaction.
  5. If you want you can also click the copy icon to the left of Try It! to copy the code snippet displayed. To change the programming language of the snippet, select one of the options under the LANGUAGE header in the right sidebar.


Example 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/json
  "account_lifecycle_event": "create",
  "originating_ip": ""

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"

What are Add-ons?

Add-ons are features of the PhoneID API that allow you to get additional information about a phone number along with the base details. You can add them to your request to get detailed information about phone numbers, such as device details, porting history, subscriber contact information, and more. The self-service API only supports the Contact add-on. For more details, see Get Started with Add-ons.

Response Value Tables

These tables explain the meaning of certain codes and other enumerated values that may be included in the response.

Next Steps

Check out these related pages:

Did this page help you?