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:


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.

InputsDescriptionValueAPI calls
firstA first name. Example – first=veronicafirst namecontact append, demographic append,
online audience
lastA last, or surname. Example – last=queklast namecontact append, demographic append,
online audience
fullnameA person first and last namefull namebusiness online audience
addressFull street address for consumer or business.
Example – address="7530 164th Ave NE"
number and streetcontact append, demographic append,
online audience
address2'address2="Ste A204"'The unit number or suite of an append, demographic append,
online audience
cityA city.
Example – city=Anaheim
city namecontact append, demographic append,
online audience
stateTwo letter state or province abbreviation, or full state or province name. Examples – state=COstate or province abbreviation

state or province full name
contact append, demographic append,
online audience
zipA US zip code or postal code.
Examples – zip=87402, zip=98117-2234
a zip codecontact append, demographic append,
online audience
phonePhone number
Example – phone=8003950164
Phone number, in North American Number Plan: YYYXXXNNNN for the append, demographic append,
online audience
emailEmail address
Example – [email protected]
[email protected]contact append, demographic append,
online audience
businessA business name - example: Versiumbusiness nameFirmographic append
domaina domain - example: 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.

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_timeA whole or decimal numberMaximum allowed API run time (in seconds).
rcfg_snake_caseA 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


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

curl \
-s \
-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('', {
    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, '');
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);
import requests

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

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

response ='', headers=headers, data=data)