Get full consumer contact information with the Contact API. With a consumer's contact information, you can pull all available contact information from the Versium data, including:
- Basic Contact information
- Phone numbers and validated emails.
Format
Here's the format to call the Consumer Contact API:
Example:
Email and Address append
https://api.versium.com/v2/contact?output[]=email&output[]=address&phone=5551234567
Phone Append
https://api.versium.com/v2/contact?output[]=phone&[email protected]
Multiple Phone Append
https://api.versium.com/v2/contact?output[]=phone_multiple&[email protected]&first=john&last=smith
Mobile only phone append - return individual matches only
https://api.versium.com/v2/contact?output[]=phone_mobile&match_type=indiv&[email protected]&first=john&last=smith
Output Type - what data will be returned by the API
Output type is what data will be returned back by the Contact Append API. Below are the different types of output and each have required and optional parameters as described in the below table.
Although multiple output types can be used simultaneously (for example: address[] and phone[]); it is recommended to perform separate calls for each to achieve better results.
One phone type can be used in any given query (i.e. you cannot use phone[] with phone_mobile[], etc).
| Output Type | Required Search Param. | Optional Search Param. |
|---|---|---|
| address | email OR phone OR first, last, city, state OR first, last, zip | country |
| phone | email OR address, city, state, zip OR first, last, city, state OR first, last, zip | address_2, country |
| phone_mobile | email OR address, city, state, zip OR first, last, city, state OR first, last, zip | address_2, country |
| phone_multiple | email OR address, city, state, zip OR first, last, city, state OR first, last, zip | address_2, country |
| phone OR address, city, state, zip OR first, last, city, state OR first, last, zip | address_2, country | |
| email_multiple | email OR phone OR Address, city, state, zip OR first, last, city, state OR first, last, zip | address_2, country |
Inputs - what the API uses to search
Inputs are information that the Contact Append API will use to search in the Versium REACH back end.
This API service accepts a consumer first and last name, and any other known consumer contact information in Common API Parameters. It matches your inputs with consumers in the Versium Data store, and returns consumer information, as available.
| value | description | example |
|---|---|---|
| first | A person’s first name | John |
| last | A person’s last name | Smith |
| address | A house/building number and street | 123 Main St |
| address_2 | The unit number of an address | Apt 12 or Unit 510 |
| city | A city name | Seattle |
| state | A US state province two letter abbreviation | WA |
| zip | A 5 digit US ZIP code | 98052 |
| country | A 2 digit country code (only US is supported) | US |
| phone | A valid 10 digit North American phone number | 2061235555 |
| A valid email address | [email protected] |
Optional Parameters
Optional Configuration Parameters are used to specify and configure how the Contact Append API will perform the search.
| Optional Config. Param. | Value | Description | Usage/Limitations | Notes |
|---|---|---|---|---|
| match_type | - hhld (default) - indiv | - hhld: match records at household level - indiv: match records at individual level | Can be used with all output types. | |
| cfg_maxrecs | 1 (default) -> 100 | number of returned records | Can be used with all output types. | |
| rcfg_max_time | A whole or decimal number | Maximum allowed API run time (in seconds) | Can be used with all output types. | |
| rcfg_max_emails | Integer | The maximum number of emails to return per record. | 1-6 (Max) | The param only applies to the email_multiple output. |
| rcfg_exclude_domains[] | string - an email provider domain | A list of domains to not return alternate emails from. | aol.com, yahoo.com | The param only applies to the email and email_multiple output. Like output[], this param uses bracket syntax, so a GET request would look like: rcfg_exclude_domains[]=aol.com &rcfg_exclude_domains[]=yahoo.com |