Suggest Edits

Versium API Reference

High-flying data ahead!

 

Welcome to our API reference! 👋 Here are the APIs we currently offer:

Versium APIs

Versium APIs

Just got here?

Code Examples

As you're looking at the code examples, you can switch the programming language of the examples with the tabs in the top. We provide examples in C#, cURL, Node, PHP, and Python. Have a specific request? Let us know!

Suggest Edits

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:

Function
Description

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.

Suggest Edits

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.

Suggest Edits

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.

Inputs
Description
Value
API calls

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

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

Inputs
Description
Value
API

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.

Options
Description
Values
Default

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

Example

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
Suggest Edits

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

Suggest Edits

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 .

Output name
Description

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

Output Example

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

See Also

Suggest Edits

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.

Campaign Choices
Description
APIs that Use It

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

ONLINE

Returns broad contact matches for online marketing campaigns, such as display ad targeting.

Outputs for BASIC Campaigns

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.

Output
Description

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.

Outputs for Email Campaigns

An EMAIL campaign includes all of the output from a basic campaign, plus the following additional output fields, where available:

Output
Description

email

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

Outputs for Phone Campaigns

A PHONE campaign includes all of the output for a basic campaign, and includes only records that include a phone number for the consumer.

Outputs for Cellphone Campaigns

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.

Outputs for Landline Campaigns

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.

Outputs for Mail Campaigns

A MAIL campaign includes all of the output for a basic campaign, and includes only records that include a postal address for the consumer.

Outputs for Online Campaigns

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

Output
Description

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)

Suggest Edits

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.

Keep your Key Safe!

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.

Key Security

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.

Authorization Example

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)
Suggest Edits

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.

Anatomy of an API Call

Anatomy of an API Call

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

API Response

Here's what the response from the API looks like.

API Responses

API Responses

What's Next

Try the API -- Try it out!

You may also want to check out:

Suggest Edits

Try the API

See how it all works with the consumer contact API. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/consumer
string apicall = "https://api.versium.com/v1.0/consumer?campaign=<campaign>&first=<first>&last=<last>&city=<city>&state=<state_or_province>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string callapi = client.DownloadString(apicall);
Console.WriteLine(callapi);
curl -H 'key: <my_key>' 'https://api.versium.com/v1.0/consumer?campaign=<campaign>&first=<first>&last=<last>&city=<city>&state=<state_or_province>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/consumer',
  qs: 
   { campaign: '<campaign>',
     first: '<first>',
     last: '<last>',
     city: '<city>',
     state: '<state_or_province>',
     country: '<country>',
     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/consumer?campaign=<campaign>&first=<first>&last=<last>&city=<city>&state=<state_or_province>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/consumer"

querystring = {"campaign":"<campaign>","first":"<first>","last":"<last>","city":"<city>","state":"<state_or_province>","country":"<country>", "key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

campaign
string

The type of information to return for the matched consumers. Accepted campaign types: BASIC, EMAIL, PHONE, CELLPHONE, LANDLINE, MAIL, ONLINE

first
string
required

Consumer's first name

last
string
required

Consumer's last name

address
string

Plus One Of Input -- Consumer's street address, including house number + street + suite (e.g. "7530 164th Ave NE, Ste A204")

city
string

Plus One Of Input -- Consumer's city

state
string

Plus One Of Input -- Consumer's state or province. Accepts both two-letter state or province abbreviation or full names

zip
string

Plus One Of Input -- Consumer's 5-digit zip code in the USA, or postal code elsewhere.

email
string

Plus One Of Input -- Valid email address

phone
string

Plus One Of Input -- Consumer's phone number. Accepts ten digits in the format NPANXXNNNN

country
string
required

Consumer's country code

output
string

Format you want your responses in

min_date
string

The oldest date you want records from. Example - To return records that are timestamped in 2012 or later, mindate=20120000

max_date
string

The most recent date you want records from. Example - To only return records that are timestamped before 2012, maxdate=20111231

max_recs
string

How many matched records you want returned, up to 10

 
Suggest Edits

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

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

  2. 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?

  3. 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&

  4. 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"

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

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

What's Next?

Now that you've built your own API call, you're ready to dive in:

Suggest Edits

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:

API Responses

API Responses

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.

What's Next?

Suggest Edits

What Consumer APIs are Available?

Understand consumers better

 

Consumer APIs give you access to contact, financial, social, and other information related to consumers.

API Name
API Service Call
Description & Data

Get basic contact information for consumers.

Available Data:

  • Email
  • Validated Email
  • Phone
  • Postal address
  • Alternate contact information for online audiences

Get rich insights for consumers.

Available Data:

Score consumer contact information for how likely the person is to be a real person with valid contact details

Suggest Edits

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 database, including:

  • Basic Contact information
  • Validated emails and phone numbers
  • Extended online audience contact matches

Note –

Note - Reverse Lookup APIs.

Format

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>

Inputs

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 store, and returns consumer information, as available.

Minimum Inputs:

  • first
  • last
  • country
  • Plus one of :
    • phone
    • email
    • address, city, state
    • address, zip
    • city, state
    • zip
    • state

Options

This API accepts the Common API Inputs and Options, plus the campaign option, which is case-sensitive uppercase.

Option
Description
Possible Values
Default

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.

Campaign Choices
Description

BASIC

Returns basic contact data (email, phone, address)

EMAIL

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

MAIL

Returns current postal addresses for direct mail campaigns

ONLINE

Returns broad contact matches for online marketing campaigns, such as display ad targeting.

Output

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

Example Response

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>
Suggest Edits

consumer

Get consumer contact information. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/consumer
string apicall = "https://api.versium.com/v1.0/consumer?campaign=<campaign>&first=<first>&last=<last>&city=<city>&state=<state_or_province>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string callapi = client.DownloadString(apicall);
Console.WriteLine(callapi);
curl -H 'key: <my_key>'  'https://api.versium.com/v1.0/consumer?campaign=<campaign>&first=<first>&last=<last>&city=<city>&state=<state_or_province>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/consumer',
  qs: 
   { campaign: '<campaign>',
     first: '<first>',
     last: '<last>',
     city: '<city>',
     state: '<state_or_province>',
     country: '<country>',
     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/consumer?campaign=<campaign>&first=<first>&last=<last>&city=<city>&state=<state_or_province>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/consumer"

querystring = {"campaign":"<campaign>","first":"<first>","last":"<last>","city":"<city>","state":"<state_or_province>","country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

campaign
string

The type of information to return for the matched consumers. Accepted campaign types: BASIC, EMAIL, PHONE, CELLPHONE, LANDLINE, MAIL, ONLINE

first
string
required

Consumer first name

last
string
required

Consumer last name

address
string

Plus One Of Input -- Consumer street address, including house number + street + suite (e.g. "7530 164th Ave NE, Ste A204")

city
string

Plus One Of Input -- Consumer city

state
string

Plus One Of Input -- Consumer state or province. Accepts two-letter state or province abbreviation or full names

zip
string

Plus One Of Input -- Consumer 5-digit zip code in the USA, or postal code elsewhere.

email
string

Plus One Of Input -- Valid email address

phone
string

Plus One Of Input -- Consumer phone number. Accepts ten digits in the format NPANXXNNNN

country
string

Consumer country

output
string

Format you want your responses in

min_date
string

The oldest date you want records from. Example - To return records that are timestamped in 2012 or later, mindate=20120000

max_date
string

The most recent date you want records from. Example - To only return records that are timestamped before 2012, maxdate=20111231

max_recs
string

How many matched records you want returned, up to 10

 
Suggest Edits

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 database, including:

  • 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 - Reverse Lookup APIs.

Format

Here's the format to call the Consumer Info API:

https://api.versium.com/v1.0/consumerinfo?key=<my_key>&<inputs>&<common_options>

Inputs

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 store, and returns requested consumer information.

Minimum Inputs:

  • first
  • last
  • country
  • Plus one of :
    • email
    • phone
    • address, city, state
    • address, zip
    • city, state
    • state
    • zip

Options

This API accepts any of the Common API Inputs and Options for consumers.

Outputs

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.

Output
Description
Values/Info Type

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.

Suggest Edits

consumerinfo

Try out the consumerinfo API. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/consumerinfo
string apicall = "https://api.versium.com/v1.0/consumerinfo?first=<first>&last=<last>&zip=<zip_or_postal_code>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string callapi = client.DownloadString(apicall);
Console.WriteLine(callapi);
curl -H 'key: <my_key>' 'https://api.versium.com/v1.0/consumerinfo?first=<first>&last=<last>&zip=<zip_or_postal_code>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/consumerinfo',
  qs: 
   { first: '<first>',
     last: '<last>',
     zip: '<zip_or_postal_code>',
     country: '<country>',
     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/consumerinfo?first=<first>&last=<last>&zip=<zip_or_postal_code>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/consumerinfo"

querystring = {"first":"<first>","last":"<last>","zip":"<zip_or_postal_code>","country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

first
string
required

Consumer first name

last
string
required

Consumer last name

address
string

Plus One Of Input -- Consumer street address, including house number, street, and suite number (e.g. "7530 164th Ave NE, Ste A204")

city
string

Plus One Of Input -- Consumer city

state
string

Plus One Of Input -- Consumer state or province. Accepts a two-letter state or province abbreviation and full names

zip
string

Plus One Of Input -- Consumer 5-digit zip code in the USA, or postal code elsewhere.

email
string

Plus One Of Input -- Valid email address

phone
string

Plus One Of Input -- Consumer phone number. Accepts ten digits NPANXXNNNN

country
string

Consumer country

output
string

Format you want your responses in

min_date
string

The oldest date you want records from. Example - To return records that are timestamped in 2012 or later, mindate=20120000

max_date
string

The most recent date you want records from. Example - To only return records that are timestamped before 2012, maxdate=20111231

max_recs
string

How many matched records you want returned, up to 10

 
Suggest Edits

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

API Name
API Service Call
Available Data

Get basic contact information for business people.

Available Data:

  • 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
Suggest Edits

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 – Business information is available for businesses in the EU. See Business Info Lookup.

Note - Reverse Lookup APIs.

Format

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>

Inputs

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
    • email
    • address, city, state
    • address, zip
    • city, state
    • state
    • zip

Options

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.

Option
Description
Accepted Values

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.

Campaign Choices
Description

BASIC

Returns basic business person contact data (name, email, phone, address, title, business)

EMAIL

Returns validated business emails for direct email campaigns

MAIL

Returns current business postal addresses for direct mail campaigns

ONLINE

Returns broad contact matches for online marketing campaigns, such as display ad targeting.

Output

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.

Suggest Edits

businesscontact

Requires a Business API plan. Try out the businesscontact API. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/businesscontact
string apicall = "https://api.versium.com/v1.0/businesscontact?campaign=<campaign>&first=<first>&last=<last>&business=<business>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string call = client.DownloadString(apicall);
Console.WriteLine(call);
curl -H 'key: <my_key>'  'https://api.versium.com/v1.0/businesscontact?campaign=<campaign>&first=<first>&last=<last>&business=<business>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/businesscontact',
  qs: 
   { campaign: '<campaign>',
     first: '<first>',
     last: '<last>',
     business: '<business>',
     country: '<country>',
     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/businesscontact?campaign=<campaign>&first=<first>&last=<last>&business=<business>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/businesscontact"

querystring = {"campaign":"<campaign>","first":"<first>","last":"<last>","business":"<business>","country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

campaign
string

Type of information you want for the business person. Can be BASIC, EMAIL, MAIL, or ONLINE.

first
string
required

Business person first name

last
string
required

Business person last name

business
string

Plus One Of Input -- Name of the business

domain
string

Plus One Of Input -- Website of the business. For example, versium.com

address
string

Plus One Of Input -- Business address

city
string

Plus One Of Input -- Business city

state
string

Plus One Of Input -- Business state or province. Accepts two-letter state or province abbreviations, or a full name

zip
string

Plus One Of Input -- Business 5-digit zip code in the USA, or postal code elsewhere

email
string

Plus One Of Input -- Email for the business or business contact

phone
string

Plus One Of Input -- Business phone

country
string

Business country

output
string

Format you want your responses in.

min_date
string

The oldest date you want records from. Example - To return records that are timestamped in 2012 or later, select a mindate of 20120000

max_date
string

The most recent date you want records from. Example - To only return records that are timestamped before 2012, enter a maxdate of 20111231

max_recs
string

How many matched records you want returned, up to 10.

 
Suggest Edits

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 database, including:

  • Branches
  • Firmographics
  • Financials (for public companies)
  • Similar businesses

Note – This API provides only business information, which is available for the EU.

Note - Reverse Lookup APIs.

Format

Here's the format to call the Business Info API:

https://api.versium.com/v1.0/businessinfo?key=<my_key>&<inputs>&<common_options>

Inputs

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:

Input
Description

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

Options

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.

Output

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.

Basic Output

Here are the basic outputs provided from the Business Contact Lookup API:

Name
Description

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)

Firmographics Output

Here are the firmographics provided, where available.

Name
Description

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)

Financial Output

Here is the Financial information provided, where available. Financial information is usually only available for public companies.

Output field
Description

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

Suggest Edits

businessinfo

Requires a Business API plan. Get information about a business. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/businessinfo
string apicall = "https://api.versium.com/v1.0/businessinfo?business=<business>&domain=<domain>&ticker=<ticker>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string call = client.DownloadString(apicall);
Console.WriteLine(call);
curl -H 'key: <my_key>' 'https://api.versium.com/v1.0/businessinfo?business=<business>&domain=<domain>&ticker=<ticker>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/businessinfo',
  qs: { business: '<business>',
  domain: '<domain>',
  ticker: '<ticker>',
  country: '<country>',
  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/businessinfo?business=<business>&domain=<domain>&ticker=<ticker>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/businessinfo"

querystring = {"business":"<business>","domain":"<domain<","ticker":"<ticker>","country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

business
string

Plus One Of Input -- Name of the business.

domain
string

Plus One Of Input -- Website for the business. For example, versium.com

ticker
string

Plus One Of Input -- Ticker symbol for the business.

address
string

Business street address

city
string

Business city

state
string

Business state or province. Accepts two-letter state or province abbreviation, or full name

zip
string

Business 5-digit zip code in the USA, or postal code elsewhere

phone
string

Business phone

email
string

Business email

country
string

Business country

output
string

Format you want your responses in.

min_date
string

The oldest date you want records from. Example - To return records that are timestamped in 2012 or later, select a mindate of 20120000

max_date
string

The most recent date you want records from. Example - To only return records that are timestamped before 2012, enter a maxdate of 20111231

max_recs
string

How many matched records you want returned, up to 10.

 
Suggest Edits

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 database, including:

  • IP Business name and address
  • IP Business domain
  • IP range
  • IP country, region, city and postal or zip code

Note – This API provides only business information, which is available for the EU.

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.

Format

Here's the format to call the IP Info API.

https://api.versium.com/v1.0/ipinfo?key=<my_key>&<inputs>&<options>

Inputs

This API service accepts a IP address. It finds the business that owns the IP address and returns business information.

Minimum input:

  • ip

Options

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.

Output

This API returns all of the following outputs:

Name
Description

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

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/ipinfo
string apicall = "https://api.versium.com/v1.0/ipinfo?ip=<ip>&key=<my_key>";

WebClient client = new WebClient();
string call = client.DownloadString(apicall);
Console.WriteLine(call);
curl -H 'key: <my_key>' 'https://api.versium.com/v1.0/ipinfo?ip=<ip>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/ipinfo',
  qs: 
   { ip: '<ip>',
     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/ipinfo?ip=<ip>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/ipinfo"

querystring = {"ip":"<ip>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

ip
string
required

An IP address

output
string

The format you want the results in. Accepts json or xml.

 

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

$.get('http://yoursite.com/test/' + id, function(data) {
    console.log(data);
});
Suggest Edits

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.

API Name
API Service Call
Description and Data

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)

Suggest Edits

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.

Format

Here's the format to call the Match API.

https://api.versium.com/v1.0/match?key=<mykey>&<inputs>&<match_inputs>&<option>

Inputs

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
  • email
  • 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
Inputs
Description
Value

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

Options

This API accepts the following Common Options:

  • output

Outputs

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:

Score
Match Strength
Suggested Action

High

De-duplicate or Merge records

Equivocal

Manually check records

Low

Keep both records

Examples

These examples show the possible results from closely and partially matched records:

Close Match

Partial Match

Suggest Edits

match

Match consumer contact information. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/match
string apicall = "https://api.versium.com/v1.0/match?first=<first>&last=<last>&email=<email>&phone=<phone>&country=<country>&match_first=<first>&match_last=<last>&email=<email>&phone=<phone>&match_country=<country>&key=<my_key>";

WebClient client = new WebClient();
string callapi = client.DownloadString(apicall);
Console.WriteLine(callapi);
curl -H 'key: <my_key>'  'https://api.versium.com/v1.0/match?first=<first>&last=<last>&email=<email>&phone=<phone>&country=<country>&match_first=<first>&match_last=<last>&email=<email>&phone=<phone>&match_country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/consumer',
  qs: 
   { first: '<first>',
     last: '<last>',
     email: '<email>',
     phone: '<phone>',
     country: '<country>',
     match_first: '<first>',
     match_last: '<last>',
     match_email: '<email>',
     match_phone: '<phone>',
     match_country: '<country>',
     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/match?first=<first>&last=<last>&email=<email>&phone=<phone>&country=<country>&match_first=<first>&match_last=<last>&email=<email>&phone=<phone>&match_country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/consumer"

querystring = {"first":"<first>","last":"<last>","email":"<email>","phone":"<phone>","country":"<country>","match_first":"<first>","match_last":"<last>","match_email":"<email>","match_phone":"<phone>","match_country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

first
string

First name for the reference person

match_first
string

First name to match

last
string

Last name for the reference person

match_last
string

Last name to match

business
string

Business the reference person works at.

match_business
string

Business to match

domain
string

Domain of the reference person's business.

match_domain
string

Domain to match

email
string

Email address

match_email
string

Email to match

phone
string

Phone number. Accepts ten digits in the format NPANXXNNNN

match_phone
string

Phone number to match

address
string

Street address, including house number + street + suite (e.g. "7530 164th Ave NE, Ste A204")

match_address
string

Street address to match

city
string

City

match_city
string

City to match

state
string

State or province. Accepts two-letter state or province abbreviation or full names

match_state
string

State or province to match

zip
string

5-digit zip code in the USA, or postal code elsewhere.

match_zip
string

5-digit zip or postal code to match

country
string

Country

match_country
string

Country to match

output
string

Format you want your responses in

 
Suggest Edits

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 warehouse tracks a number of indicators to create a score based on behavioral and demographic attributes, online activity, and other proprietary measures.

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 - Reverse Lookup APIs.

Format

Here's the format to call the Consumer ID Score API:

https://api.versium.com/v1.0/consumeridentityscore?key=<mykey>&<inputs>&<commonoptions>

Inputs

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 database and known fictitious markers, and returns a score indicating how likely it is the consumer name and contact information are real vs. fictitious.

Minimum Inputs

  • first
  • last
  • phone
  • email
  • Any additional information you have (the more you specify, the better our scoring can be):
    • address
    • city
    • state
    • zip
    • ip address

Outputs

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"
Suggest Edits

consumeridentityscore

Score the validity of consumer contact information. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/consumeridentityscore
string apicall = "https://api.versium.com/v1.0/consumeridentityscore?first=<first>&last=<last>&email=<email>&phone=<phone>&address=<address>&city=<city>&state=<state_or_province>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string call = client.DownloadString(apicall);
Console.WriteLine(call);
curl -H 'key: <my_key>'  'https://api.versium.com/v1.0/consumeridentityscore?first=<first>&last=<last>&email=<email>&phone=<phone>&address=<address>&city=<city>&state=<state_or_province>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/consumeridentityscore',
  qs: 
   { first: '<first>',
     last: '<last>',
     phone: '<phone>',
     email: '<email>',
     address: '<address>',
     city: '<city>',
     state: '<state_or_province>',
     country: '<country>',
     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/consumeridentityscore?first=<first>&last=<last>&email=<email>&phone=<phone>&address=<address>&city=<city>&state=<state_or_province>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/consumeridentityscore"

querystring = {"first":"<first>","last":"<last>","phone":"<phone>","email":"<email>","address":"<address>","city":"<city>","state":"<state_or_province>","country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

first
string
required

Consumer's first name

last
string
required

Consumer's last name

phone
string
required

Consumer's phone number. Accepts ten digits in the format NPANXXNNNN

email
string
required

Valid email address

zip
string

Consumer's 5-digit zip code in the USA, or postal code elsewhere.

address
string

Consumer's street address, including house number + street + suite (e.g. "7530 164th Ave NE, Ste A204")

city
string

Consumer's city

state
string

Consumer's state or province. Accepts two-letter state or province abbreviation or full names

country
string

Consumer's country

ip
string

An IPv4 address

output
string

Format you want your responses in

 
Suggest Edits

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.

Format

Here's the format to call the Consumer Standardization API:

https://api.versium.com/v1.0/consumerstandardization?key=<my_key>&<inputs>&<common_options>

Inputs

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 store, and returns standardized consumer information.

Accepted Inputs:

  • first
  • last
  • phone
  • email
  • address, city, state
  • address, zip
  • city, state
  • zip
  • state
  • country

Options

This API accepts the Common API Inputs and Options.

Output

This API returns standardized contact information, in uppercase.

Input
Standardized Output

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.

email

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.

Suggest Edits

consumerstandardization

Get consumer contact information. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/consumerstandardization
string apicall = "https://api.versium.com/v1.0/consumerstandardization?first=<first>&last=<last>&phone=<phone>&email=<email>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string callapi = client.DownloadString(apicall);
Console.WriteLine(callapi);
curl -H 'key: <my_key>'  'https://api.versium.com/v1.0/consumerstandardization?first=<first>&last=<last>&phone=<phone>&email=<email>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/consumerstandardization',
  qs: 
   { first: '<first>',
     last: '<last>',
     phone: '<phone>',
     email: '<email>',
     country: '<country>',
     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/consumerstandardization?first=<first>&last=<last>&phone=<phone>&email=<email>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/consumerstandardization"

querystring = {"first":"<first>","last":"<last>","phone":"<phone>","email":"<email>","country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

first
string

First name

last
string

Last name

phone
string

Phone number. Accepts ten digits in the format NPANXXNNNN

email
string

Email address

address
string

Street address, including house number + street + suite (e.g. "7530 164th Ave NE, Ste A204")

city
string

City

state
string

State or province. Accepts two-letter state or province abbreviation or full names

zip
string

5-digit zip code in the USA, or postal code elsewhere.

country
string

Consumer country

output
string

Format you want your responses in

 
Suggest Edits

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.

API Name
API Service Call
Description & Data

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.

Suggest Edits

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 database, including:

  • First and last name
  • Deliverable email
  • Other contact information, such as phone and address

Note –

Format

Here's the format to call the Email Reverse Lookup API:

https://api.versium.com/v1.0/email?key=<mykey>&<inputs>&<commonoptions>

Inputs

This API service accepts an email or MD5 Hashed email address as input. It matches your input with consumer emails in the store, and returns consumer information, as available.

Minimum Inputs

email

Options

This API accepts the Common API Inputs and Options, plus the campaign option.

Option
Description
Possible Values
Default

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.

Campaign Choices
Description

BASIC

Returns basic contact data (phone, address)

EMAIL

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

MAIL

Returns current postal addresses for direct mail campaigns

ONLINE

Returns broad contact matches for online marketing campaigns, such as display ad targeting.

Output

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.

Suggest Edits

email

Look up contact information by email. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/email
string apicall = "https://api.versium.com/v1.0/email?campaign=<campaign>&email=<email>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string call = client.DownloadString(apicall);
Console.WriteLine(call);
curl -H 'key: <my_key>'  'https://api.versium.com/v1.0/email?campaign=<campaign>&email=<email>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/email',
  qs: 
   { campaign: '<campaign>',
     email: '<email>',
     country: '<country>',
     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/email?campaign=<campaign>&email=<email>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/email"

querystring = {"campaign":"<campaign>","email":"<email>","country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

email
string
required

Email address to look up

campaign
string

The type of information to return for the matched person. Accepted campaign types: BASIC, EMAIL, PHONE, CELLPHONE, LANDLINE, MAIL, ONLINE

output
string

Output format you want the results in. Default is JSON. Values can be json or xml.

country
string

Country

 
Suggest Edits

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 database, including:

  • First and last name
  • Deliverable email
  • Other contact information, such as phone and address

Note –

Format

Here's the format to call the Phone Reverse Lookup API:

https://api.versium.com/v1.0/phone?key=<mykey>&<inputs>&<commonoptions>

Inputs

This API service accepts a phone number as input. It matches your inputs with consumer phone numbers in the store, and returns consumer information, as available.

Minimum Inputs

phone

Options

This API accepts the Common API Inputs and Options, plus the campaign option.

Option
Description
Possible Values
Default

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.

Campaign Choices
Description

BASIC

Returns basic contact data (phone, address)

EMAIL

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

MAIL

Returns current postal addresses for direct mail campaigns

ONLINE

Returns broad contact matches for online marketing campaigns, such as display ad targeting.

Output

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.

Suggest Edits

phone

Look up contact information by phone. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/phone
string apicall = "https://api.versium.com/v1.0/phone?campaign=<campaign>&phone=<phone>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string call = client.DownloadString(apicall);
Console.WriteLine(call);
curl -H 'key: <my_key>' 'https://api.versium.com/v1.0/phone?campaign=<campaign>&phone=<phone>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/phone',
  qs: 
   { campaign: '<campaign>',
     phone: '<phone>',
     country: '<country>',
     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/phone?campaign=<campaign>&phone=<phone>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/phone"

querystring = {"campaign":"<campaign>","phone":"<phone>","country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

phone
string
required

Phone number you want to look up

campaign
string

The type of information to return for the matched person. Accepted campaign types: BASIC, EMAIL, PHONE, CELLPHONE, LANDLINE, MAIL, ONLINE

output
string

Output format you want the results in. Default is JSON. Values can be json or xml.

country
string

Country

 
Suggest Edits

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 database, including:

  • First and last name
  • Deliverable email
  • Other contact information, such as phone and address

Note –

Format

Here's the format to call the Address Reverse Lookup API:

https://api.versium.com/v1.0/address?key=<mykey>&<inputs>&<commonoptions>

Inputs

This API service accepts an address as input. It matches your inputs with consumer addresses in the store, and returns consumer information, as available.

Minimum Inputs

address

Options

This API accepts the Common API Inputs and Options, plus the campaign option.

Option
Description
Possible Values
Default

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.

Campaign Choices
Description

BASIC

Returns basic contact data (phone, address)

EMAIL

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

MAIL

Returns current postal addresses for direct mail campaigns

ONLINE

Returns broad contact matches for online marketing campaigns, such as display ad targeting.

Output

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.

Suggest Edits

address

Look up contact information by address. Returned results use your monthly matches.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.versium.com/v1.0/address
string apicall = "https://api.versium.com/v1.0/address?campaign=<campaign>&address=<address>&city=<city>&state=<state_or_province>&country=<country>&key=<my_key>";

WebClient client = new WebClient();
string call = client.DownloadString(apicall);
Console.WriteLine(call);
curl -H 'key: <my_key>' 'https://api.versium.com/v1.0/address?campaign=<campaign>&address=<address>&city=<city>&state=<state_or_province>&country=<country>'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.versium.com/v1.0/address',
  qs: 
   { campaign: '<campaign>',
     address: '<address>',
     city: '<city>',
     state: '<state_or_province>',
     country: '<country>',
     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/address?campaign=<campaign>&address=<address>&city=<city>&state=<state_or_province>&country=<country>&key=<my_key>');
curl_exec ($ch);
curl_close($ch)
?>
import requests

url = "https://api.versium.com/v1.0/address"

querystring = {"campaign":"<campaign>","address":"<address>","city":"<city>","state":"<state_or_province>","country":"<country>","key":"<my_key>"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

address
string
required

The address you want to look up.

state
string
required

The state or province for the address you want to look up.

city
string

Plus One Of -- The city for the address you want to look up.

zip
string

Plus One Of -- The zip or postal code for the address you want to look up.

campaign
string

The type of information to return for the matched person. Accepted campaign types: BASIC, EMAIL, PHONE, CELLPHONE, LANDLINE, MAIL, ONLINE

output
string

Output format you want the results in. Default is JSON. Values can be json or xml.

country
string

Country

 
Suggest Edits

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.

Show Match Codes

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.

Change Match Codes

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

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.

What to Match
Match Code

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

Email

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

Defining the match type - Exact and Fuzzy matching

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.

Combining match codes with AND and OR

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

More Match Code Examples

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

Suggest Edits

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.

What Data do you want?
Type of Data needed?
Use this API

Contact Information
Get business or consumer contact information, such as emails, phone numbers, online audiences, and postal addresses

Consumer

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

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