Get Started with Information Lookup

Introduction

Look up the details about a phone number with a simple API request.

Phone Number Information Lookup

Voxology’s Phone Number Information Lookup API brings disparate data together in a simple service built to help developers validate phone numbers, lookup carrier information, increase notification deliverability, and reduce fraud.

Things You Can Do

  • Validate Phone Numbers // check to see if a phone number is valid
  • Identify Potential Fraud // help reduce risk of fraud by verifying the data of your signups
  • Increase Notification Deliverability // help determine the right method to deliver your message
  • Enhance Phone Experiences // craft personalized phone experiences for your user based on the information about their phone number

How It Works

Look up the underlying information about a phone number using Voxology’s REST API.

REST API

Overview

The Phone Number Information Lookup method can return the following details about a phone number: carrier name, phone number type, caller id name (cnam), rate center, lata, city/state, postal code, and country.

Your request simply needs the phone number and the type of data you want to include: location, cnam, and carrier. In addition to the details available within the include query parameter, we also support 3rd party integrations which gives you access to additional information from other leading providers, all in one response.

NOTE: Phone Number Information Lookup fees apply – see our pricing page for more details.

Example Request // Lookup Phone Number Information
curl -X GET \
  'https://api.voxolo.gy/v1/PhoneNumberInformation/+19495551212?include=cnam,carrier,location&integrations=trestle_reverse_phone' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \

Phone Number Data

Include

The data below can be returned in your phone number lookups using the include query parameter.

Basic Data
  • Local Formatting // the localized format of the phone number
  • Country // the country code of the phone number
  • Caller ID Name // the registered name (or the company name) of the caller
  • Carrier Name // the name of the carrier that is associated with the phone number
  • Line Type // the type of phone connected with the number: landline, mobile, voip
  • Location // country, region (state), city, postal code (zip), and latitude/longitude of the phone number’s designated location
  • Rate Center & LATA // the region to which the phone number is assigned
Example Response
{
   "country_code":"US",
   "phone_number":"+13238732860",
   "phone_number_formatted":"(323) 873-2860",
   "carrier":{
      "error":null,
      "carrier_name":"BANDWIDTH.COM CLEC  LLC - CA",
      "phone_number_type":"mobile"
   },
   "cnam":{
      "error":null,
      "caller_name":"JOHN DOE"
   },
   "location":{
      "time_zone":"America/Los_Angeles",
      "latitude":34.10129344875499,
      "longitude":-118.324525950829,
      "country":"US",
      "rate_center":"LOS ANGELES DA 14:Hollywood",
      "city":"Los Angeles:DA 14",
      "postal_code":"90028",
      "lata":"730",
      "region":"CA"
   },
   "error":null
}

Integrations

In addition to the location, caller id name, and carrier look ups, Voxology supports integrations with 3rd party providers using the integrations query parameter.

3rd Party Data
  • Trestle Reverse Phone Number Lookups // Trestle Reverse Phone Lookup (formally offered by Ekata Mastercard) enables you to “get an owner’s current name, address, demographics, phone details, associated people, and relatives.” A full description of the return data can be found here.
Example Response
{
  "country_code": "US",
  "phone_number": "+13238732860",
  "phone_number_formatted": "(323) 873-2860",
  "integrations": {
    "whitepages_reverse_phone": {
      "current_addresses": [
        {
          "id": "Location.abcd85c1-7ed2-420e-8af1-86ce123456f8",
          "location_type": "PostalCode",
          "street_line_1": null,
          "street_line_2": null,
          "city": "Los Angeles",
          "postal_code": "90011",
          "zip4": null,
          "state_code": "CA",
          "country_code": "US",
          "lat_long": {
            "latitude": 34.0071,
            "longitude": -118.2585,
            "accuracy": "PostalCode"
          },
          "is_active": null,
          "delivery_point": null,
          "link_to_person_start_date": null
        }
      ],
      "belongs_to": {},
      "warnings": {},
      "historical_addresses": {},
      "carrier": "Bandwidth SMSEnabled",
      "associated_people": {},
      "is_valid": true,
      "line_type": "NonFixedVOIP",
      "phone_number": "3238732860",
      "alternate_phones": {},
      "id": "Phone.12345fef-a2e0-4b08-cfe3-bc7128b54321",
      "country_calling_code": "1"
    }
  },
  "error": null
}

You can view a full list of Phone Number Information Lookup options on the API Reference.


Getting Started

Get started with Voxology’s Phone Number Information Lookup API.

Lookup Phone Number Information

Overview

This tutorial is a step-by-step guide to looking up the information of a phone number using the Voxology API.

Prerequisites

Tutorial

1. Select the Type of Phone Number Information You Want To Look up

To look up the details about a phone number, first determine which information you want to include: location, cnam (caller id name), carrier, and/or other third party integrations.

You may choose to combine any include types or integrations types in your request. In this example, we will show you how to use both.

2. Prepare Your Request

After you have selected the type of Phone Number Information you want to receive, prepare your REST request. This requires your API Key, the phone number (in E.164 format), and your desired query parameters. See the example below which includes carrier, cnam (caller id name), and Trestle Reverse Phone Lookup.

curl -X GET \
  'https://api.voxolo.gy/v1/PhoneNumberInformation/+13238732860?include=cnam,carrier&integrations=trestle_reverse_phone' \
  -H 'Cache-Control: no-cache' \
  -H 'content-type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'
3. Make Your Request

Once your request is prepared, send it to receive information about the phone number. If your request was a success, you will see a JSON response that looks like the following.

{
  "country_code": "US",
  "phone_number": "+13238732860",
  "phone_number_formatted": "(323) 873-2860",
  "carrier": {
    "error": null,
    "carrier_name": "BANDWIDTH.COM CLEC  LLC - CA",
    "phone_number_type": "mobile"
  },
  "cnam": {
    "error": null,
    "caller_name": "JOHN DOE"
  },
  "integrations": {
    "whitepages_reverse_phone": {
      "current_addresses": [
        {
          "id": "Location.abcd85c1-7ed2-420e-8af1-86ce123456f8",
          "location_type": "PostalCode",
          "street_line_1": null,
          "street_line_2": null,
          "city": "Los Angeles",
          "postal_code": "90011",
          "zip4": null,
          "state_code": "CA",
          "country_code": "US",
          "lat_long": {
            "latitude": 34.0071,
            "longitude": -118.2585,
            "accuracy": "PostalCode"
          },
          "is_active": null,
          "delivery_point": null,
          "link_to_person_start_date": null
        }
      ],
      "belongs_to": {},
      "warnings": {},
      "historical_addresses": {},
      "carrier": "Bandwidth SMSEnabled",
      "associated_people": {},
      "is_valid": true,
      "line_type": "NonFixedVOIP",
      "phone_number": "3238732860",
      "alternate_phones": {},
      "id": "Phone.12345fef-a2e0-4b08-cfe3-bc7128b54321",
      "country_calling_code": "1"
    }
  }
}

Congratulations! You are now ready to look up information about phone numbers. You can view a full list of Phone Number Information Lookup options on the API Reference.