Common Inputs and API Parameters

Versium REACH API services share many common inputs parameters and options. These common elements are covered in this section.
For case-sensitivity rules, see API Case Sensitivity.

Output Types - what data will be returned back by the API

The Contact Append and Demographic Append APIs will require a mandatory output type to select the type of data that will be returned.
The output type is different between APIs and can be defined as an array for multiple types.

The possible output types are the following:

API	output[]
contact	phone
contact	phone_mobile
contact	phone_multiple
contact	address
contact	email
demographic	demographic
demographic	financial
demographic	lifestyle
demographic	political

Common Inputs - what the API uses to search

All of the consumer APIs require at least an output type (see above) and a search input parameter from the following; first name, last name, country, and any 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	contact append, demographic append, online audience
last	A last, or surname. Example – `last=quek`	last name	contact append, demographic append, online audience
fullname	A person first and last name	full name	business online audience
address	Full street address for consumer or business. Example – `address="7530 164th Ave NE"`	number and street	contact append, demographic append, online audience
address2	'address2="Ste A204"'	The unit number or suite of an address.	contact append, demographic append, online audience
city	A city. Example – `city=Anaheim`	city name	contact append, demographic append, online audience
state	Two letter state or province abbreviation, or full state or province name. Examples – `state=CO`	state or province abbreviation state or province full name	contact append, demographic append, online audience
zip	A US zip code or postal code. Examples – `zip=87402`, `zip=98117-2234`	a zip code	contact append, demographic append, online audience
phone	Phone number Example – `phone=8003950164`	Phone number, in North American Number Plan: YYYXXXNNNN for the US.	contact append, demographic append, online audience
email	Email address Example – `[email protected]`	[email protected]	contact append, demographic append, online audience
business	A business name - example: Versium	business name	Firmographic append
domain	a domain - example: versium.com	.	Firmographic append

Configuration Parameters

Use these options to adjust the response you get back from the API, such as the maximum number of records you want to receive. These options work for most of the Versium REACH APIs.

Options	Description	Values
match_type (string)	Used to return a Household (HHLD) or Individual (INDIV) record.	only applicable with the “contact” API. Values are - indiv - hhld
cfg_maxrecs (integer)	The maximum amount of records to be returned in the response.	This will limit the number of records returned in the response. Default is 1.
rcfg_max_time	A whole or decimal number	Maximum allowed API run time (in seconds).
rcfg_snake_case	A boolean to to return key names in snake case, instead of upper case with spaces.	Boolean (example: 1)
rcfg_suppression_ids[]	When used, the API will use a specific Suppression Lists identified with its own ID. If not specified, by default all suppression lists will be referenced by the API.	single suppression list: rcfg_suppression_ids[]=3 multiple suppression lists: rcfg_suppression_ids[]=3&rcfg_suppression_ids[]=10

Example

This example searches for a consumer named Veronica Quek in zip code 92117.

curl \
-s https://api.versium.com/v2/contact? \
-H "X-Versium-Api-Key: <api key>" \
-d first=veronica \
-d last=quek \
-d zip=92117 \
-d output[]=email
-d output[]=address

var fetch = require('node-fetch');

fetch('https://api.versium.com/v2/contact?', {
    method: 'POST',
    headers: {
        'X-Versium-Api-Key': '<api key>'
    },
    body: 'first=veronica&last=quek&zip=92117&output[]=email&output[]=address'
});

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.versium.com/v2/contact?');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "first=veronica&last=quek&zip=92117&output[]=email&output[]=address");
$headers = array();
$headers[] = 'X-Versium-Api-Key: <api key>';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

import requests

headers = {
    'X-Versium-Api-Key': '<api key>',
}

data = [
  ('first', 'veronica'),
  ('last', 'quek'),
  ('zip', '92117'),
  ('output[]', 'email'),
  ('output[]', 'address'),
]

response = requests.post('https://api.versium.com/v2/contact', headers=headers, data=data)