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