Versium API Reference
High-flying data ahead!
Welcome to our API reference! 👋 Here are the APIs we currently offer:
Just got here?
- To get started, head on over to Get Started with Versium APIs or the API Walkthroughs
- For a list of all of the data we have, see All the Data.
- For categorized data, see The Versium API Roadmap.
API Details
Nitty gritty details for those of you that need it. You know who you are.
See the The Versium API Roadmap for all of the API calls available.
The API was developed using RESTful principles, and returns JSON responses by default. See Common API Inputs and Options for options to change the output.
For case-sensitivity rules, see API Case Sensitivity.
The API also uses common approaches for the following:
Data
API data is JSON encoded with UTF-8. API JSON is either a single object or a list of objects.
Authorization
Access control using API Access Tokens.
Errors
4xx and 5xx responses returning JSON with error codes
Rate Limiting
Controls how many requests can be made in a time window
HTTP/HTTPS
Methods are used in accordance with HTTP (GET, POST and DELETE are the primary methods used) and resources are identified using URIs. All API requests are sent over HTTPS.
API Case Sensitivity
Where you need to pay attention to case, and where you don't
There are a few places in the API where case matters. They are:
Option names -- The name of each option is case-sensitive. For example, first, state, max_recs, The value you provide for the option is not case-sensitive.
Api key -- Your API key is case sensitive, so provide it exactly as it appears on the developer portal. You can easily copy it from the Manage API Key page.
Everywhere else in the API, case doesn't matter, including:
The API call URI -- The https API call. For example .../v1/phone and ...V1/PHONE both work.
Option values -- The value you provide for an option. For example, first=sue, first=SUE and first=Sue will all return the same results.
Common API Inputs and Options
These things work all over the API.
Versium API services share many common inputs and options. These common elements are covered in this section. For case-sensitivity rules, see API Case Sensitivity.
Common Consumer Inputs
The consumer APIs take a consumer contact name, and any other known contact information. All of the consumer APIs require at least a first name, last name, country, and one other piece of identifying information to ensure accurate and manageable results.
first
A first name. Example – first=veronica
first name
consumer, consumerinfo, businesscontact, consumeridentityscore, match, consumerstandardization
last
A last, or surname. Example – last=quek
last name
consumer, consumerinfo, businesscontact, consumeridentityscore, match, consumerstandardization
zip
A US zip code or postal code.
Examples – zip=87402
, zip=V9H 1A6
, zip=98117-2234
a zip or
postal code
consumer, consumerinfo, businesscontact, consumeridentityscore, match, consumerstandardization
address
Full street address for consumer or business.
Example – address="7530 164th Ave NE, Ste A204"
"number street suite"
consumer, consumerinfo, businesscontact, consumeridentityscore, match, consumerstandardization
city
A city.
Example – city=Anaheim
"city name"
consumer, consumerinfo, businesscontact, consumeridentityscore, match, consumerstandardization
state
Two letter state or province abbreviation, or full state or province name. Examples – state=CO
, or state=alberta
state or province abbreviation
state or province full name
consumer, consumerinfo, businesscontact, consumeridentityscore, match, consumerstandardization
phone
Phone number
Example – phone=8003950164
Phone number, in NPANXXNNNN for the US. Other country formats accepted.
consumer, consumerinfo, businesscontact, consumeridentityscore, , phone, match, consumerstandardization
Email address
Example – email=me@domain.com
account@domain.com
consumer, consumerinfo, businesscontact, consumeridentityscore, match, consumerstandardization
ip
IP address in xxx.xxx.xxx.xxx format Example – ip=122.122.022.322
ip_address
consumer, consumerinfo, ipinfo, consumeridentityscore, businesscontact, business
country
2-letter country code (supported country codes). Defaults to US. Example - country=CN
country_code
All
Common Business Inputs
The business API services take a business or business contact name, and any other known contact information. When you're specifying a business contact name, use the same input options as the consumer APIs (first, middle, and last).
business
Name of a business.
Example -business="Versium Inc"
businessname
"business name"
business, businesscontact
domain
Root URL of the business. Example - domain=versium.com
domain
business, businesscontact
ticker
Ticker symbol for the business. Example - ticker=FBRK
ticker
business
Common Options
Use these options to adjust the response you get back from the API, such as the output language or maximum number of records you want to receive. These options work for most of the Versium APIs.
output
The format you want your responses in. Example - output=json
json
xml
json
min_date
The oldest date you want records from. Example - To return records that are timestamped in 2012 or later, min_date=20120101
yyyymmdd
max_date
The most recent date you want records from. Example - To only return records that are timestamped before 2012, max_date=20111231
yyyymmdd
min_match_score
Set the minimum match score for returned records. 100 is matches perfectly. See Advanced Matching. Example - min_match_score=40
0-100
0
max_recs
Set how many matched records you want returned, up to 10. Example - max_recs=3
1-10
10
Here's an example using several common inputs and options as inputs into the businessinfo API call, and will return information for the top 3 matches for "Versium Inc."
https://api.versium.com/v1.0/businessinfo?key=<my_api_key>&business="Versium Inc"&domain=versium.com&output=xml&max_recs=3
This example searches for a consumer named Veronica Quek in Washington state, and returns the top 20 matches.
https://api.versium.com/v1.0/consumer?key=<mykey>&first=veronica&last=quek&state=wa&max_recs=20
"Plus one of" Inputs
APIs where one additional input from a list is required
Many of the APIs have required inputs, and then a requirement for one other input chosen from a list of what we call "Plus one of" Inputs. When you see a "Plus One Of" option, it means the API requires at least one of those options, and it doesn't matter which one you provide. You can provide more than one, as well.
Sometimes, you'll need to provide more than one of these inputs to make sure your request is clear (for example, if you provide an address, you'll need the city and state or zip to make sure it searches for the correct address; if you provide a city, you'll need the state or zip).
On the "Try It" API pages, these inputs are marked as "Plus One Of" and grouped right after the required inputs so it's easy for you to see which inputs you can choose from.
Common Outputs
Returned with every API call
Versium API services share a few common outputs that are returned for all Versium APIs. To see sample results, go to Make Your First API Call .
version
The version of the API service used.
query_id
An ID unique to each query, useful if you need to troubleshoot.
results
Contains the results of the API call - this is the information you've asked for.
input_query
Shows the inputs and options you used to make the API call
num_results
Gives the number of match records for the given search parameters
page_time
How long the API call lookup took
match_score
Gives the match score for the result. 0 is no match and 100 is a perfect match to your inputs. If you need finer control over matching, see Advanced Matching.
time_stamp
The date and time this data was saved
Here's an example of the output you can expect:
{
Versium: {
version: "1.0",
num_results: 1,
query_id: "b42e46ed6baf6d2785062b97e9548ab5",
query_time: "0.193",
results: [
{
match_score: 100,
time_stamp: "20130906",
first: "VERONICA",
middle: "M",
last: "QUEK",
address: "1480 MAIN ST",
city: "WHEATON",
state: "IL",
zip: "60187",
country: "US",
phone: "6305551212",
line_type: "Landline"
}
],
input_query: {
first: "Veronica",
last: "Quek",
email: "vquek@aol.com",
country: "US",
max_recs: "10",
min_date: "20101010",
output: "json",
campaign: "basic"
}
}
}
Output for Campaign Types
Here's what you get for each campaign type
You choose a campaign option to control the type of output that you get from several of the Versium APIs: consumer, businesscontact, phone, and email.
This table shows the data validation and output results for each type of campaign. Example: campaign=EMAIL.
BASIC
Returns basic contact data (email, phone, address)
Returns validated emails for direct email campaigns
PHONE
Returns active mobile and home phone numbers for direct phone campaigns phone
CELLPHONE
Returns active mobile phone numbers for direct phone campaigns
LANDLINE
Returns active home phone numbers for direct phone campaigns
Returns current postal addresses for direct mail campaigns
ONLINE
Returns broad contact matches for online marketing campaigns, such as display ad targeting.
Here are the outputs returned, where available, when you specify campaign=BASIC. Note that for consumers, all of the results apply to the consumer. For business contact lookup, the address, city, state, zip, and country will be for the business.
first
First name
middle
Middle name
last
Last name
address
Street address
city
City
state
State or province
zip
Zip or postal code
phone
Phone number
line_type
The line type of the phone number. For example, "line_type": "Landline." See note below.
title
Businesscontact only -- Title of the business person.
business
Businesscontact only -- Name of the business.
Note -- Due to factors like number portability, there is up to a 10% inaccuracy with the line_type result.
An EMAIL campaign includes all of the output from a basic campaign, plus the following additional output fields, where available:
Best match email address for the consumer
valid_email
Best match validated email address for the consumer
ip
If available, the IP address where the email was found
url_source
If available, the URL where the email was found
A PHONE campaign includes all of the output for a basic campaign, and includes only records that include a phone number for the consumer.
A CELLPHONE campaign includes all of the output for a basic campaign, and includes only records that include a known mobile phone number for the consumer.
A LANDLINE campaign includes all of the output for a basic campaign, and includes only records that include a known landline phone number for the consumer.
A MAIL campaign includes all of the output for a basic campaign, and includes only records that include a postal address for the consumer.
An ONLINE campaign includes all of the output for a basic campaign, and includes the following additional output fields for online campaign cooking matching, where available.
Caution
online_email
Best match online email address associated with the inputs.
alt_name
Alternate names associated with the inputs.
alt_emails
Additional email addresses associated with the inputs, in order of match strength, with strongest match first.
alt_phone
Alternate phone numbers associated with the inputs.
alt_address
Alternate addresses associated with the input names.
Social Note: The social data returned varies based on the type of data requested, as available. For consumers, the API returns Facebook information, and for business contacts, the API returns LinkedIn information.
fb_name
Facebook name (see social note above)
fb_uid
Facebook ID (see social note above)
fb_url
Facebook URL (see social note above)
li_name
Name on LinkedIn (see social note above)
li_uid
ID on LinkedIn (see social note above)
li_url
URL to LinkedIn profile (see social note above)
Authorization
It's all about that key... 'bout that key...
You use your API secret key to authorize your API calls. It's like your password for your API calls. Create your account and get your API key by checking out Get Started with Versium APIs. Your key is case-sensitive.
Your key is what allows you to access the API, and is used to determine your API usage for billing, so keep it safe! Be careful not share your secret API key in places where it may be visible publicly, such public GitHub repos or in your client-side code. If you think your API key has been compromised, contact API Support to get a new key.
To keep your API key safe, the Versium API uses the following guidelines:
HTTP Basic Auth -- The Versium API uses HTTP Basic Auth. You provide your key for the basic auth username value. You do not need to provide a password.
HTTPS -- You must make all API requests over HTTPS. API requests over HTTP or without authorization will fail.
Here's an example of how to provide your API key in cURL and https.
-H "key: <my_key>" \
https://api.versium.com/v1.0/<api_service>
https://api.versium.com/v1.0/<api_service>?key=<my_key>
var request = require("request");
var options = { method: 'GET',
url: 'https://api.versium.com/v1.0/<api_service>',
qs:
{ options: '<option_value>',
key: '<my_key>'} };
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.versium.com/v1.0/<api_service>?options=<option_values>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests
url = "https://api.versium.com/v1.0/<api_service>"
querystring = {"options":"<option_values>","key":"<my_key>"}
response = requests.request("GET", url, params=querystring)
print(response.text)
Make Your First API Call
It doesn't have to be hard
At the most basic level, you call the Versium APIs through HTTPs. Here's a sample call that searches business person contact information for Karen Berg, and only returns records that contain a deliverable email address.
For case-sensitivity rules, see API Case Sensitivity.
Here's the code in HTTPs to copy and edit. If you'd like to try it in C#, cURL, Javascript, Node, PHP, or Python, go to Try the API].
https://api.versium.com/v1.0/consumer?key=<my_key>&first=Karen&last=Berg&state=WA&campaign=EMAIL
Here's what the response from the API looks like.
Try the API -- Try it out!
You may also want to check out:
Try the API
See how it all works with the consumer contact API. Returned results use your monthly matches.
Build Your Own API Call
Step-by-step how to call a Versium API with https
Here's the format of Versium API calls:https://api.versium.com/v1.0/<service>?key=<my_key>&<inputs>&<options>
And here's how you build your own...
Find the API Call -- Find the URL for the API service that gets the information you need in The Versium API Roadmap. Our samples use the Business Info API. Here's the URL for that API service:
https://api.versium.com/v1.0/businessinfo
Start call options -- This step simply adds a question mark to the URL, which indicates to the browser that options follow to be passed to the API service.
https://api.versium.com/v1.0/businessinfo?
Add your API key -- Adding your API key lets the API service confirm that the call is authorized. You add your API key followed by &. The & character tells the API that the current option is done and another one is coming. Make sure there's one in between all of your inputs and options. In the call below, replace "my_key" with the Versium API key you got when you created an account. For help, see Find your API key.
https://api.versium.com/v1.0/businessinfo?key=my_key&
Add your inputs -- Add what you want to search for, again separated by &. See the The Versium API Roadmap and Common API Inputs and Options. For example, this API call uses the business= and city= inputs to specify the business name and city for the company we want information on.
https://api.versium.com/v1.0/businessinfo?key=my_key&business=tesla&city="palo alto"
Add API options -- Add options to control what kind of output you get. For example, output=json specifies you want the output in JSON format.
https://api.versium.com/v1.0/businessinfo?key=my_key&business=tesla&city="palo alto"&output=json
Call the API service in a secure browser -- When you're done adding inputs and options, you're ready to call the API. Over a secure internet connection, copy and paste the call you've built into your browser search window, and press Enter.
Your results will appear where a web page usually displays in your browser window.
Now that you've built your own API call, you're ready to dive in:
- Interpret API results
- Check out the Try It Out sections in the Versium API Reference
- See the The Versium API Roadmap for all of the possible API calls
- Walk through one of the API Walkthroughs
- Learn the case-sensitivity rules for the API, see API Case Sensitivity
Interpret API results
What to do with all that data
Here's a sample of what you'll get back from the API (in the default JSON format), and how to interpret it:
To interpret the results you've received, see the Outputs section of the API reference topic for the output specific to that API call, plus Common Outputs for outputs that are common across all of the Versium APIs.
Here's where you can go next:
What Consumer APIs are Available?
Understand consumers better
Consumer APIs give you access to contact, financial, social, and other information related to consumers.
Get basic contact information for consumers.
Available Data:
- Validated Email
- Phone
- Postal address
- Alternate contact information for online audiences
Get rich insights for consumers.
Available Data:
- Demographics
- Interests and Activities
- Household Financial and Auto
- Social presence
- Predictive Scores
- … and more
Score consumer contact information for how likely the person is to be a real person with valid contact details
Consumer Contact API
Looking to contact consumers? Here's where you get their contact information.
Available in the following plans: All plans
Get full consumer contact information with the Consumer API. With a consumer's full name country, and one other identifying piece of information, you can pull all available contact information from the
- Basic Contact information
- Validated emails and phone numbers
- Extended online audience contact matches
Note –
Note -
Here's the format to call the Consumer Contact API:
https://api.versium.com/v1.0/consumer?key=<my_key>&<inputs>&campaign=<campaign_type>&<common_options>
This API service accepts a consumer first and last name, and any other known consumer contact information in Common API Inputs and Options It matches your inputs with consumers in the
Minimum Inputs:
- first
- last
- country
- Plus one of :
- phone
- address, city, state
- address, zip
- city, state
- zip
- state
This API accepts the Common API Inputs and Options, plus the campaign option, which is case-sensitive uppercase.
campaign
Selects the type of information to return for the matched consumers.
BASIC, EMAIL, CELLPHONE, LANDLINE, PHONE, MAIL, ONLINE
BASIC
Campaign Description
The campaign type you specify filters the output you receive. This table shows the data validation and output results for each type of campaign. Example: campaign=EMAIL.
BASIC
Returns basic contact data (email, phone, address)
Returns validated emails for direct email campaigns
PHONE
Returns active mobile and home phone numbers for direct phone campaigns phone
CELLPHONE
Returns active mobile phone numbers for direct phone campaigns
LANDLINE
Returns active home phone numbers for direct phone campaigns
Returns current postal addresses for direct mail campaigns
ONLINE
Returns broad contact matches for online marketing campaigns, such as display ad targeting.
This API returns the Output for Campaign Types for the campaigns it supports, and the Common Outputs, such as match_score and timestamp. If the field is blank, it is not returned.
Caution
Here's the output of the above API call, in JSON and XML.
{
Versium: {
version: "1.0",
num_results: 1,
query_id: "b42e46ed6baf6d2785062b97e9548ab5",
query_time: "0.193",
results: [
{
match_score: 100,
time_stamp: "20130906",
first: "VERONICA",
middle: "M",
last: "QUEK",
address: "1480 MAIN ST",
city: "WHEATON",
state: "IL",
zip: "60187",
country: "US",
phone: "6305551212",
line_type: "Landline"
}
],
input_query: {
first: "Veronica",
last: "Quek",
email: "vquek@aol.com",
country: "US",
max_recs: "10",
min_date: "20101010",
output: "json",
campaign: "BASIC"
}
}
}
<Versium>
<version>1.0</version>
<num-results>1</num-results>
<query-id>5042451fc2c88751012caa68fe322531</query-id>
<query-time>0.151</query-time>
<results>
<record id="0">
<matchscore>100</matchscore>
<timestamp>20130906</timestamp>
<firstname>ROBERTA</firstname>
<middlename>M</middlename>
<lastname>CACIOPPO</lastname>
<address>1480 S COUNTY FARM RD</address>
<city>WHEATON</city>
<state>IL</state>
<zip>60187</zip>
<country>US</country>
<phone>6306177313</phone>
<linetype>Landline</linetype>
</record>
</results>
<input-query>
<firstname>roberta</firstname>
<lastname>CACIOPPO</lastname>
<email>robear28@aol.com</email>
<country>US</country>
<maxrecs>10</maxrecs>
<mindate>20101010</mindate>
<output>json</output>
<campaign>basic</campaign>
</input-query>
</Versium>
Consumer Info API
Get insights on consumers, including demographics and financial data
Available in the following plans: All plans
Improve your ability to personalize your marketing campaigns by adding valuable demographic insights to your customer lists with consumer insights from the ConsumerInfo API. With a consumer's name, country, and one other identifying piece of information, pull rich consumer insights from the
- Individual and household demographics, such as age range and marital status.
- Interests & activities
- Purchase behavior
- Finances, such as their household income
- What type of car they drive.
Note –
Note -
Here's the format to call the Consumer Info API:
https://api.versium.com/v1.0/consumerinfo?key=<my_key>&<inputs>&<common_options>
This API service accepts a consumer name, and any other known contact information in Common API Inputs and Options It matches your inputs with consumers in the
Minimum Inputs:
- first
- last
- country
- Plus one of :
- phone
- address, city, state
- address, zip
- city, state
- state
- zip
This API accepts any of the Common API Inputs and Options for consumers.
In addition to the output below, this API also returns the Common Outputs, such as matchscore and timestamp. If the field is blank, it is not returned.
Basic Output
first
Consumer first name
middle
Consumer middle name
last
Consumer last name
address
Consumer street address
city
Consumer city
state
Consumer state or province
zip
Consumer zip or postal code
phone
Consumer phone number
line_type
The line type of the phone number (see note)
**Household Output
home_value
A range for the estimated value of the home
length_of_residence
The number of years the consumer has lived in the home.
home_purchase_date
The date the home was originally purchased
home_purchase_price
The price the home was originally purchased at, in thousands.
dwelling_type
Indicates the type of home the consumer lives in. Results shown as M, S, or U.
M = Multiple Family Dwelling Unit
S = Single Family Dwelling Unit U = Unknown
Demographic Output
age_range
Consumer estimated age range
single_parent
Consumer is a single parent
Yes or blank (see note)
senior_adult_in_household
A senior adult is in the household in addition to the primary adult (senior adult is age 55+)
Yes or blank (see note)
young_adult_in_household
A young adult is in the household in addition to the primary adult (young adult is ages 18 to 25)
Yes or blank (see note)
working_woman
A working woman is in the household
Yes or blank (see note)
soho
A single owner home office (SOHO) is in the household
Yes or blank (see note)
business_owner
Type of business in the household
Accountant
Builder
Contractor
Dealer/Retailer/Storekeeper
Distributor/Wholesaler
Funeral Director
Maker Manufacturer,
Owner
Partner
Self-Employed
implied_language
Language likely spoken in the household
number_of_children
Number of children in the household
marital_status_in_household
Marital status of the household
M = Married
S = Single
A = Inferred Married
B = Inferred Single
home_owner_renter
Household is owned or rented
Own or Rent
education
Consumer education level
occupation
Consumer occupation
occupation_detail
Additional consumer occupation details
gender
Gender of the consumer
Male or Female
social_presence
Consumer has a social platform profile
Yes or blank (see note)
presence_of_children
Children are present in the household
Yes or blank (see note)
Lifestyle Outputs
magazines
Household has a magazine subscription
Yes or blank (see note)
computer_and_technology
Interest in computers and technology in household
Yes or blank (see note)
dieting_weight_loss
Interest in dieting or weight loss in household
Yes or blank (see note)
exercise_health_grouping
Interest in exercise or health in household
Yes or blank (see note)
diy_home_improvement
Interest in do-it-yourself home improvement in household
Yes or blank (see note)
jewelry
Interest in jewelry in household
Yes or blank (see note)
mail_order_buyer
Buys by mail order in household
Yes or blank (see note)
membership_clubs
Interest in membership clubs in household
Yes or blank (see note)
travel
Interest in travel in household
Yes or blank (see note)
online_education
Interest in online education in household
Yes or blank (see note)
sports
Interest in sports in household
sports_outdoors
Interest in outdoor sports in household
Yes or blank (see note)
investing
Interest in investing in household
Yes or blank (see note)
books_and_reading
Interest in books and reading in household
Yes or blank (see note)
political_donor
Household has made political donations
Yes or blank (see note)
hobbies_and_crafts
Interest in hobbies and crafts in household
Yes or blank (see note)
cosmetics
Interest in cosmetics in household
Yes or blank (see note)
charitable_donations
Household has made charitable donations
Yes or blank (see note)
arts_antiques_collectibles
Interest in arts, antiques, and collectibles in household
Yes or blank (see note)
pet_owner
Household owns pets
Yes or blank (see note)
cooking
Interest in cooking in household
Yes or blank (see note)
auto_parts_accessories
Interest in auto parts and accessories in household
Yes or blank (see note)
health_beauty_wellness
Interest in health, beauty, and wellness in household
Yes or blank (see note)
parenting_and_childrens_products
Interest in parenting and children's products in household
Yes or blank (see note)
music
Interest in music in household
Yes or blank (see note)
movies
Interest in movies in household
Yes or blank (see note)
self_improvement
Interest in self-improvement in household
Yes or blank (see note)
womens_apparel
Interest in Women's apparel in household
Yes or blank (see note)
estimated_household_income
Estimated income for the household
Auto Output
auto_year
Year of automobile in household
auto_make
Make of automobile in household
auto_type
Type of automobile in household
Linetype Note -- Due to factors like number portability, there is up to a 10% inaccuracy with the linetype result.
Yes or Blank Note -- For output with a value of Yes or blank, Yes means the data suggests this is true, and blank means we did not find any data to support this demographic. If the field is blank, it is not returned.
What Business APIs are Available?
Understand businesses and business people better
Business APIs give you access to contact, financial, social, and other information related to businesses. Available in the following plans: Any Business Access Plan
Get basic contact information for business people.
- Business Person Contact
- Title
- Business Person Online audience - Online audience - Online audience is alternate contact information that is closely associated with your matched consumers or business people that can be invaluable in display-ad and other online targeting of consumers and business people. Online audience contact data should not be used for direct campaigns, as it may be older, out of date, or otherwise not appropriate for direct marketing campaigns.
- How You’re Connected
- Org Chart
- Business insights (as below)
Get rich insights for businesses.
Available Data:
- Business Contact Information
- Business Name
- Firmographics
- Business Financial
- Social
- Business News
- Standard Business Scores
- Business Structure
Get detailed business information about an IP address.
Available Data:
- Business Name
- Business contact information
- Domain
- IP range for the business
- IP country, region, city, and zip
Business Person Contact API
Looking to contact a business person? Get their contact information here.
Available in the following plans: Any Business Access Plan
Look up business person contact information with the BusinessContact API call. With a business person's full name, country, and one other identifying piece of information, pull contact information from the Versium LifeData® database, including:
- Business person Contact information
- Validated deliverable emails
- Extended online audience contact matches
Note –
Note -
Here's the format to call the Business Contact API:
https://api.versium.com/v1.0/businesscontact?key=<my_key>&<inputs>&campaign=<CAMPAIGN>&<common_options>
This API service accepts a business, business domain, business person's name, location, and any other known contact information in Common API Inputs and Options. It matches your inputs with business people in the Versium LifeData® store, and returns requested business person contact information.
Minimum input:
- first
- last
- country
- Plus one of :
- business
- domain
- phone
- address, city, state
- address, zip
- city, state
- state
- zip
Use the campaign option to fine-tune the information you receive. This service also accepts the common options in Common API Inputs and Options, that allow you to specify match codes and scores, the output format, maximum number of records, and other options.
campaign
What type of information to return
BASIC
EMAIL
MAIL
ONLINE
Campaign Description
The campaign type you specify filters the output you receive. This table shows the data validation and output results for each type of campaign. Example: campaign=EMAIL.
BASIC
Returns basic business person contact data (name, email, phone, address, title, business)
Returns validated business emails for direct email campaigns
Returns current business postal addresses for direct mail campaigns
ONLINE
Returns broad contact matches for online marketing campaigns, such as display ad targeting.
This API returns the Output for Campaign Types for the campaigns it supports, and the Common Outputs, such as match_score and time_stamp. If the field is blank, it is not returned.
businesscontact
Requires a Business API plan. Try out the businesscontact API. Returned results use your monthly matches.
Business Info API
Look up business information.
Available in the following plans: Any Business Access Plan
Get rich information on businesses to improve your ability to find, target and connect with the ideal businesses for your campaigns with the Business Info API call. With a business name and country, pull business information from the
- Branches
- Firmographics
- Financials (for public companies)
- Similar businesses
Note –
Note -
Here's the format to call the Business Info API:
https://api.versium.com/v1.0/businessinfo?key=<my_key>&<inputs>&<common_options>
This API service accepts a business name, domain, and any other known contact information in Common API Inputs and Options. It matches your inputs with businesses in the Versium LifeData® store, and returns requested business information.
Minimum input:
- country
- Plus one of :
- business
- domain
- ticker
business
Business name
domain
Website URL or domain
ticker
Ticker symbol for the business
zip
Zip or postal code. Example: zip=87402
address
Full business street address. Number + street + suite (e.g. "7530 164th Ave NE, Ste A204")
Example: address=123 lucky ln
city
City for the business
Example: city=Anaheim
state
Two letter state abbreviation
Example: state=CO
phone
Ten digits NPANXXNNNN
Example: phone=8003950164
country
Required - business country. Defaults to US
This service has no additional options, and accepts the common options in Common API Inputs and Options, that allow you to specify match codes and scores, the output format, maximum number of records, and other options.
In addition to the output below, this API also returns the Common Outputs, such as match_score and time_stamp.
This API returns all of the following outputs, where available: Basic, Firmographics, and Financials. If the field is blank, it is not returned. See the following sections for descriptions.
Here are the basic outputs provided from the Business Contact Lookup API:
business
Business name
domain
Business website
address
Street address for the business
city
City for the business
state
State or province for the business
zip
Zip or postal code for the business
phone
Phone number for the business (business phone, personal phone, or company phone)
Here are the firmographics provided, where available.
num_employees
Number of employees range (current ranges)
type
Type of business (for example, public or private)
location_type
Type of location for the business (for example, headquarters or subsidiary)
year_founded
The year the business was founded
sic
SIC code (US) for the business
sic_description
Description for the SIC code (US)
Here is the Financial information provided, where available. Financial information is usually only available for public companies.
revenue
Yearly revenue for the business
revenue_growth
Yearly growth as a percentage
ticker
Stock ticker symbol
total_cash
Total cash (in US dollars)
total_debt
Total debt (in US dollars)
enterprise_value
Total company value
businessinfo
Requires a Business API plan. Get information about a business. Returned results use your monthly matches.
IP Info API
Look up detailed business information for the business that owns an IP address.
Available in the following plans: Any Business Access Plan
Create solutions for targeting B2B marketing campaigns using actionable information about the ownership of an IP address. Determine if the IPs visiting your website are companies worth marketing to, all with the IP Info API call. With an IP address, you can pull IP business information from the
- IP Business name and address
- IP Business domain
- IP range
- IP country, region, city and postal or zip code
Note –
Note - This service does not provide a reverse look up for the person or user of an IP address. It provides a lookup for the business that owns the IP address. Reverse phone, email and address lookup are available through the Reverse Lookup APIs.
Here's the format to call the IP Info API.
https://api.versium.com/v1.0/ipinfo?key=<my_key>&<inputs>&<options>
This API service accepts a IP address. It finds the business that owns the IP address and returns business information.
Minimum input:
- ip
This service has no additional options, and accepts the following common options:
- output
For more information on common options, see Common API Inputs and Options, that allow you to specify match codes and scores, the output format, maximum number of records, and other options.
This API returns all of the following outputs:
business
Business name that owns the IP address
domain
Website for the business that owns the IP address
address
Street address for the business that owns the IP address
city
City for the business that owns the IP address
state
State or province for the business that owns the IP address
zip
Zip or postal code for the business that owns the IP address
phone
Phone number for the business (business phone or company phone) that owns the IP address
ip_from
Start or IP range for the business that owns the IP address
ip_to
End of IP range for the business that owns the IP address
ip_country
Country where the IP is registered
ip_region
Region where the IP is registered
ip_city
City where the IP is registered
ip_zip
Postal or zip code where the IP is registered
ipinfo
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
$.get('http://yoursite.com/test/' + id, function(data) {
console.log(data);
});
What Data Prep APIs are there?
Data Prep APIs allow you to clean, de-duplicate, merge and purge your data to improve your data processing efficiency and reduce costs on campaigns.
Compare business or people information to de-duplicate records. Returns a score from 0 to 100 indicating how closely the records match.
Score consumer contact information for how likely the person is to be a real person with valid contact details
Standardize your consumer information (US, UK and Canada)
Match API
Compare name and contact information to de-duplicate and merge records
Available in the following plans: All plans
The Match API helps you identify duplicate records in your CRM or other customer lists, covering both business (B2B) and consumer (B2C) data. Compare business or consumer records to identify potential duplicates so you can de-duplicate or tag potential duplicates in your data.
This API service accepts business or consumer information for two people or businesses, and:
- Compares the two using Versium's advanced matching engine and fuzzy matching
- Provides a score indicating how closely the two records match. The score ranges from 0-100, with 0 indicating no match and 100 indicating a perfect match.
Here's the format to call the Match API.
https://api.versium.com/v1.0/match?key=<mykey>&<inputs>&<match_inputs>&<option>
This API accepts business or consumer information for two people or businesses. The match score is based on how many of the inputs match the match_inputs. If you provide an input and do not provide the corresponding match_input, it will reduce the score.
First record inputs
- first
- last
- business
- domain
- phone
- address
- city
- state
- zip
Match record inputs
- match_first
- match_last
- match_business
- match_domain
- match_phone
- match_email
- match_ address
- match_city
- match_state
- match_zip
first, match_first
A first name. Examples – first=veronica
match_first=veronica
first name
last, match_last
A last, or surname. Examples – last=quek
match_last=quek
last name
business, match_business
Name of a business. Examples - business=Versium, Inc
match_business=versium
business
domain, match_domain
Root URL of the business. Examples - domain=versium.com
match_domain=versium.com
URL
zip, match_zip
A 5-digit zip code in the USA, or postal code elsewhere.
Examples – zip=87402
match_zip=84702
5-digit zip
postal code
address, match_address
Full street address for consumer or business.
Examples – address="7530 164th Ave NE, Ste A204"
match_address="7530 164th Ave NE, #A204"
"number street suite"
city, match_city
A city.
Examples – city=Anaheim
match_city=anaheim
"city name"
state, match_state
Two letter state or province abbreviation, or full state or province name. Examples – state=CO
, or state=alberta
match_state=CO
state or province abbreviation
state or province full name
phone, match_phone
Phone number
Example – phone=8003950164
match_phone=8883950164
Phone number, in NPANXXNNNN for the US. Other country formats accepted.
email, match_email
Email address
Example – email=me@domain.com
match_email=you@domain.com
account@domain.com
country, match_country
2-letter country code (supported country codes). Example - country=CN
match_country=CN
country_code
This API accepts the following Common Options:
- output
This API returns a match score that indicates how closely the two records match. You may need to fine-tune the actions for your particular application; however, here are some guidelines to start with:
High
De-duplicate or Merge records
Equivocal
Manually check records
Low
Keep both records
Consumer Identity Score API
Get a picture of how real your consumer contact data is with our Identity Score
Available in the following plans: All plans
Verify that a contact or lead/prospect is a real person with real contact information. The Consumer Identity Score provides a measure of confidence for your contact information. Versium's extensive
You can use this score to identify and remove fictitious consumer contact information from your lists for marketing campaigns, lead acquisition, or to provide a hygiene function in front of predictive modeling and other machine-learning algorithms.
Note –
Note -
Here's the format to call the Consumer ID Score API:
https://api.versium.com/v1.0/consumeridentityscore?key=<mykey>&<inputs>&<commonoptions>
This API service accepts a consumer's name and contact information as in Common API Inputs and Options. It compares the inputs you provide with our
Minimum Inputs
- first
- last
- phone
- Any additional information you have (the more you specify, the better our scoring can be):
- address
- city
- state
- zip
- ip address
This API returns a score from 0 to 100, with 0 being no confidence and 100 being high confidence that the contact information is real. The score is built by adding points for positive indicators (such as name and contact information has been found together) and subtracting points for negative indicators (such as email domain is a temporary email site).
Scores above 40 generally indicate the contact record is likely a real person, however the input data may be partially incomplete or obsolete. Other factors can also reduce the score.
Below 40, the identity is most likely fictitious. For example, a score in the 20-25 range generally indicates that the input data supplied meets all the validation and formatting criteria, however no match can be found for the combination of data that was submitted.
Confidence level is also returned for key contact information:
- High -- The person appears to be associated with the contact information.
- Medium -- The information was found, but it's either not closely associated or has some other indicator that reduces confidence
- Low -- The information was not found, or it was found on suspect lists.
Examples
These example results indicate it's reasonably likely this contact information is real:
identity_score: 100,
name_confidence: "high",
email_confidence: "high",
phone_confidence: "high",
address_confidence: "high"
identity_score: 65,
name_confidence: "high",
email_confidence: "high",
phone_confidence: "high",
address_confidence: "medium"
These example results indicate it's highly likely this contact information is fictitious:
identity_score: 20,
name_confidence: "high",
email_confidence: "low",
phone_confidence: "medium",
address_confidence: "low"
identity_score: 1,
name_confidence: "low",
email_confidence: "low",
phone_confidence: "low",
address_confidence: "low"
consumeridentityscore
Score the validity of consumer contact information. Returned results use your monthly matches.
Consumer Standardization API
Standardize your consumer contact information.
Available in the following plans: All plans
Standardize your consumer contact information with the Consumer Standardization API call.
You provide your consumer contact info, including name, address, phone, and email, and get back the same information in standard, clean, uppercase format.
Notes
This API does not validate any contact information. To validate the data, use Consumer Identity Score.
Because this API only cleans inputs that you provide, GDPR restrictions do not apply.
Here's the format to call the Consumer Standardization API:
https://api.versium.com/v1.0/consumerstandardization?key=<my_key>&<inputs>&<common_options>
This API service accepts a consumer first and last name, and any other known consumer contact information in Common API Inputs and Options. It matches your inputs with consumers in the
Accepted Inputs:
- first
- last
- phone
- address, city, state
- address, zip
- city, state
- zip
- state
- country
This API accepts the Common API Inputs and Options.
This API returns standardized contact information, in uppercase.
first
Input value, all uppercase.
last
Input value, all uppercase.
phone
If the input is:
- A US phone number, returns standard US 10-digit number
- A UK phone number, returns standard UK phone number.
- A Canadian phone number, returns standard Canadian phone number.
- If the phone number is not recognized as a US, UK, or Canadian phone number, no value is returned.
Returns standardized email, all uppercase.
zip
If the input is:
- US Zip4, returns standard "plus-four" zip
- US Zip5, returns standard Zip5
- US Zip9, returns standard Zip9
- UK Postal Code, returns standard UK postal code
- Canada Postal code, returns standard Canadian postal code
- If the postal code is not recognized as a US, UK, or Canadian postal code, no value is returned.
address
Returns standardized address, all uppercase.
city
Returns city, all uppercase.
state or province
Returns state or province, all uppercase.
country
Returns 2-letter country abbreviation, all uppercase.
consumerstandardization
Get consumer contact information. Returned results use your monthly matches.
What Reverse Lookup APIs are Available?
Have an email, phone, or address and want to know who it belongs to? Reverse Lookup APIs can help!
Reverse Lookup APIs let you start with a piece of contact information -- email, phone, or address- and look up consumers associated with it.
Find full name and contact information from an email or hashed email.
Find full name and contact information from a phone number.
Find full name and contact information from an address.
Email Reverse Lookup API
Look up consumers by their email addresses
Available in the following plans: All plans
Fill in all of your customer information using only an email address with the Email Reverse Lookup API. Provide just an email address or a MD5 hashed email address, and pull contact information and insights from the
- First and last name
- Deliverable email
- Other contact information, such as phone and address
Note –
Here's the format to call the Email Reverse Lookup API:
https://api.versium.com/v1.0/email?key=<mykey>&<inputs>&<commonoptions>
This API service accepts an email or MD5 Hashed email address as input. It matches your input with consumer emails in the
Minimum Inputs
This API accepts the Common API Inputs and Options, plus the campaign option.
campaign
Selects the type of information to return for the matched consumers.
BASIC, EMAIL, PHONE, CELLPHONE, LANDLINE, MAIL, ONLINE
BASIC
Campaign Description
The campaign type you specify filters the output you receive. This table shows the data validation and output results for each type of campaign. For example: campaign=EMAIL.
BASIC
Returns basic contact data (phone, address)
Returns validated emails for direct email campaigns
PHONE
Returns active mobile and home phone numbers for direct phone campaigns
CELLPHONE
Returns active mobile phone numbers for direct phone campaigns to cellphones
LANDLINE
Returns active home phone numbers for direct phone campaigns to landlines
Returns current postal addresses for direct mail campaigns
ONLINE
Returns broad contact matches for online marketing campaigns, such as display ad targeting.
This API returns the Output for Campaign Types, and the Common Outputs, such as match_score and timestamp. If the field is blank, it is not returned.
This API returns both Consumer and Business data
If the email being looked up belongs to a consumer, you'll get consumer information. If it belongs to a business, you'll get business information.
Phone Reverse Lookup API
Look up consumers by phone number.
Available in the following plans: All plans
Fill in all of your customer information using only a phone number with the Phone Reverse Lookup API. Provide just a phone number, and pull contact information and insights from the
- First and last name
- Deliverable email
- Other contact information, such as phone and address
Note –
Here's the format to call the Phone Reverse Lookup API:
https://api.versium.com/v1.0/phone?key=<mykey>&<inputs>&<commonoptions>
This API service accepts a phone number as input. It matches your inputs with consumer phone numbers in the
Minimum Inputs
phone
This API accepts the Common API Inputs and Options, plus the campaign option.
campaign
Selects the type of information to return for the matched consumers.
BASIC, EMAIL, CELLPHONE, LANDLINE, PHONE, MAIL, ONLINE
BASIC
Campaign Description
The campaign type you specify filters the output you receive. This table shows the data validation and output results for each type of campaign. For example: campaign=EMAIL.
BASIC
Returns basic contact data (phone, address)
Returns validated emails for direct email campaigns
PHONE
Returns active mobile and home phone numbers for direct phone campaigns phone
CELLPHONE
Returns active mobile phone numbers for direct phone campaigns
LANDLINE
Returns active home phone numbers for direct phone campaigns
Returns current postal addresses for direct mail campaigns
ONLINE
Returns broad contact matches for online marketing campaigns, such as display ad targeting.
This API returns the Output for Campaign Types, and the Common Outputs, such as match_score and timestamp. If the field is blank, it is not returned.
This API returns both Consumer and Business data
If the phone number being looked up belongs to a consumer, you'll get consumer information. If it belongs to a business, you'll get business information.
Address Reverse Lookup API
Look up consumers by postal address.
Available in the following plans: All plans
Fill in all of your customer information using only a mailing address with the Address Reverse Lookup API. Provide just a postal address, and pull contact information and insights from the
- First and last name
- Deliverable email
- Other contact information, such as phone and address
Note –
Here's the format to call the Address Reverse Lookup API:
https://api.versium.com/v1.0/address?key=<mykey>&<inputs>&<commonoptions>
This API service accepts an address as input. It matches your inputs with consumer addresses in the
Minimum Inputs
address
This API accepts the Common API Inputs and Options, plus the campaign option.
campaign
Selects the type of information to return for the matched consumers.
BASIC, EMAIL, CELLPHONE, LANDLINE, PHONE, MAIL, ONLINE
BASIC
Campaign Description
The campaign type you specify filters the output you receive. This table shows the data validation and output results for each type of campaign. For example: campaign=EMAIL.
BASIC
Returns basic contact data (phone, address)
Returns validated emails for direct email campaigns
PHONE
Returns active mobile and home phone numbers for direct phone campaigns
CELLPHONE
Returns active mobile phone numbers for direct phone campaigns
LANDLINE
Returns active home phone numbers for direct phone campaigns
Returns current postal addresses for direct mail campaigns
ONLINE
Returns broad contact matches for online marketing campaigns, such as display ad targeting.
This API returns the Output for Campaign Types, and the Common Outputs, such as match_score and timestamp. If the field is blank, it is not returned. This API only returns consumer information.
address
Look up contact information by address. Returned results use your monthly matches.
Advanced Matching
For more precise control of how the API matches your inputs
The default matching algorithms are optimized for each API call, and work for most use cases. If you need finer control over matching, you can specify how you'd like the APIs to match your inputs.
Caution
Modifying the default match codes can affect the quality and quantity of the results from the APIs. Read this topic to understand how match codes work, and then fully test your changes to ensure the result is what you want.
For more information about fuzzy and exact matching, see How Matching Approach and Data Sources Affect Your Results.
To see what match codes are being used, use the match_code_output option. For example -- match_code_output=True
This option tells the API to include the match codes it used for the results returned.
Once you know what match codes are being used, you can refine how the API is matching records. To specify how to match, use the apply_match_code option. For example --apply_match_code=LF0,P,ACSZ
Match Codes specify how you want the API to match your inputs, allowing you to more finely control how the API matches records and what it returns.
Both first and last
LF:
- LF0 - First and Last name match exactly
- LF - First and last name partially or fuzzy match
First name
F
Last name
L
Middle name
M
Address
A
Address number
AHN
Address street
AS
Address unit
AU
City
C
State
S
City and state
CS
Zip or postal code
Z
Country code
IC
Phone
P
Address, city, state, and zip
ACSZ
E
Social
H
Business name
B
Title
T
Domain name
DOM
Ticker symbol
TS
IP address
IP
The probability of the individual's name being unique in the specified area. PINDIV1-4 only apply to the US.
PINDIV:
- PINDIV4 = Probably unique to City/State,
- PINDIV3 = Probably unique to CBSA,
- PINDIV2 = Probably unique to State,
- PINDIV1 = Probably unique to US,
- PINDIV0 = Probably unique worldwide
The probability of the business name being unique in the specified area. BINDIV1-4 only apply to the US.
BINDIV:
- BINDIV4 = Probably unique to City/State,
- BINDIV3 = Probably unique to CBSA,
- BINDIV2 = Probably unique to State
- BINDIV1 = Probably unique to US
- BINDIV0 = Probably unique worldwide
Specifies the area to search for matches. For example, if you specify a zip code and DIST4, the API will search within the entire metro area that the specified zip is in.
DIST:
- DIST0=address
- DIST1=zip
- DIST2=city
- DIST3=ziplist
- DIST4=metro
- DIST9=World
Inputs matched at the Individual level
INDIV
Inputs matched at the Household level
HHLD
Location Type is Headquarters
ILT0
The numbers after returned match codes indicate the degree of the match. If you want to match exactly, add a 0 (zero) to the match code. For example, LF0 means the first and last name matched exactly.
No number means the element was a partial, or fuzzy match.
You can perform AND and OR on match codes. Do not use any spaces:
- AND - Use commas. To find matches that match for all match codes, you can AND the codes using a comma. In some cases, you can just concatenate (see second example below, and supported combinations in the table)
- OR -- Use semicolons (OR).
AND/OR Examples
- Match City AND State, OR match the zip exactly --
apply_match_code=C0,S0;Z0
- Match address, city, state, and zip --
apply_match_code=ACSZ
- Match email or phone exactly --
apply_match_code=E0;P0
Here are some examples using match codes:
Look up records that exactly match the name and state
https://api.versium.com/v1.0/consumer?key=<mykey>&first=veronica&last=quek&state=wa&apply_match_code=LF,S0
Return records that exactly match the phone number --
apply_match_code=P0
Return records that partially match the phone number --
apply_match_code=P
Return records that match first, last, address (City/State or Zip), and phone, partially -- apply_match_code=P,LF,ACSZ
Return records that exactly match the phone and partially match first and last, OR the first/last partially match and the email is an exact match. -- apply_match_code=P0,LF;LF,E0
All the Data
Where to look for the data you want
Find the type of data you need, then click the link to the API that gets you access to it.
Contact Information
Get business or consumer contact information, such as emails, phone numbers, online audiences, and postal addresses
Consumer
Business
Standardized Consumer Information
Clean up records by getting consumer information in a standardized format
Consumer
Insights
Get business or consumer insights, such as business financials and company size, or consumer demographics, interests and activities, and automobile type.
Consumer
Business
IP Business
Reverse Phone, Email, or Address Lookup
Get a name and contact information from an email, phone, or address
Contact info from Email
Contact info from Phone
Contact info from Address
Identity Scores
Score the consumer contact information you have to gauge if the information is real or fake
Consumer Identity Scores
De-duplicate and merge records
Score two records on how closely they match to assist in de-duplicating business and consumer customer records.
Match business or consumer records