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

Check them out!

• What Consumer APIs are Available?
• What Business APIs are Available?
• What Data Prep APIs are there?
• What Reverse Lookup APIs are Available?

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!

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:

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.

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.

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

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.

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

This example searches for a consumer named Veronica Quek in Washington state, and returns the top 20 matches.

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.

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 .

Here's an example of the output you can expect:

Output for Campaign Types

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.

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.

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:

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.

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.

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

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

Try the API -- Try it out!

You may also want to check out:

• Build Your Own API Call
• Interpreting the API results
• API Walkthroughs

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.

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

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:

• Common Outputs
• Try the API
• API Walkthroughs
• API Case Sensitivity

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

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.

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

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

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

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.

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.

Here's the output of the above API call, in JSON and XML.

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.

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

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

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.

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.

Business APIs give you access to contact, financial, social, and other information related to businesses. Available in the following plans: Any Business Access Plan

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.

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

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

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

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.

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.

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

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

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:

Here are the firmographics provided, where available.

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

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.

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

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:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

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.

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.

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

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:

Examples

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

Close Match

Partial Match

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.

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

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

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"

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:

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

This API accepts the Common API Inputs and Options.

This API returns standardized contact information, in uppercase.

Reverse Lookup APIs let you start with a piece of contact information -- email, phone, or address- and look up consumers associated with it.

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 –

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

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

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

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.

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.

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 –

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

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

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

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.

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.

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 –

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

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

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

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.

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.