API Overview - Datafinder is a service of Versium

Online Audience Builder API Documentation

Online Audience BuilderOverview

Datafinder's Online Audience Builder API service enables you to programmatically append alternate contact information to your customer or prospect lists. Fill in the alternate contact information such as alternate email addresses, phone numbers, and postal addresses.

Inputs and outputs:

For a complete list of inputs please see the "Parameters" section. For a complete list of outputs, please see the "Output Fields" section.

Please note: Emails and other contact data supplied for an online audience are not appropriate for direct communication marketing campaigns. Maintain your IP reputation and ability to send emails by using only Versium-validated emails for direct campaigns. You can get validated emails with our Consumer Email append. For more information, see Best Practices for Email Campaigns.

Request URL

https://api.datafinder.com/v2/qdf.php?k2={your-key}&service=onlineAudience

Parameters

Config Parameters

Use the configuration parameters to adjust what the API returns, such as like the output format.

Name	Description	Required?
k2	Your api key	Yes
service	Which API service to use. Use "email" or "phone" in this case.	Yes
output	Specify json or xml output responses. Default is JSON. Example: output=json
cfg_mc	Specify the required match codes for a result to be returned. A match codes represents a match between the value of an input field and the value of a field in a record. For example, if the first name of your input and the first name of the output record are the same, an F0 match code is returned Example: cfg_mc=INDIV - This will return a record only if it is an individual level match For a list of all match codes, see the Match Codes page.

Search Parameters

Any parameter that begins with a "d_" is a search parameter. We will use these parameters to try to match an individual or household. Some search parameters do not return results if used by themselves, such as d_last or d_first. If a search parameter requires another, it is noted in the table below.

NOTE: d_first and d_last are required for an individual level match.

Name	Description
d_first	A first name. Requires: d_last, and one of the following: d_email, d_phone, d_fulladdr, d_city and; d_state, d_fulladdr, d_zip, d_dob, or d_lat and d_long Example:d_first=john
d_last	A last name. Requires: d_first, and one of the following: d_email, d_phone, d_fulladdr, d_city and; d_state, d_fulladdr, d_zip, d_dob, or d_lat and d_long Example:d_last=Doe
d_fullname	A first and last name. Requires: one of the following: d_email, d_phone, d_fulladdr, d_city and; d_state, d_fulladdr, d_zip, d_dob, or d_lat and d_long Example:d_fullname=john smith
d_zip	A 5-digit zip code in the USA. Requires: d_fulladdr Example:d_zip=87402
d_fulladdr	Entire house number + street + suite (e.g. "7530 164th Ave NE, Ste A204") Requires: d_city and d_state, or d_zip Example:d_fulladdr=123 lucky ln
d_city	A city in the USA. Requires: d_fulladdr, d_state Example: d_city=Anaheim
d_state	Two letter state abbreviation Requires: d_fulladdr and d_city, or d_fulladdr and d_zip Example: d_state=CO
d_phone	Ten digits NPANXXNNNN Example: d_phone=8003950164
d_email	Valid email address Example: d_email=account_name@domain.com

Output Fields

The API results follow the schema shown below and include:

version - API version
query-id - id unique to each query
results - list of append results
input-query - list of input search parameters and their values
num-results - number of match records for the given search parameters
query-time - how long the processing took
page-time - how long the lookup took

Fields returned for each record in the "results":

Name	Description
_RawMatchCodes	See the Match Codes page
_NormalizedRawScore	A score between 0 and 100 that represents the strength of the match
EmailAddr	An email address
Phone	A phone number
Address	A street address
City	A city
State	A state
Zip	A zip
@EmailAddr	A pipe (\|) -delimited list of additional email addresses and timestamps related to the input data
@Phone	A pipe-delimited list of additional phone numbers and timestamps related to the input data
@FullAddr	A pipe-delimited list of additional postal addresses and timestamps related to the input data

Output schema in JSON:

{
  "datafinder": {
    "version": "2.0",
    "query-id": "xxxxxx",
    "results": [
      {
        "key": "value"
      }
    ],
    "input-query": {
      "key": "value"
    },
    "num-results": 1,
    "query-time": "0.000",
    "page-time": "0.000"
  }
}

If we cannot match the input search parameters to a record then no results will be returned. The result would appear as follows:

{
  "datafinder": {
    "version": "2.0",
    "query-id": "xxx",
    "input-query": {
      "FirstName": "John",
      "LastName": "Doe",
      "EmailAddr": "john.doe@domain.com"
    },
    "num-results": 0,
    "query-time": "0.138",
    "page-time": "0.193"
  }
}

Example Queries and Response

Search for contact information using a phone (household level match):

https://api.datafinder.com/v2/qdf.php?k2=key&service=onlineAudience&d_phone=5555555555&d_first=john&d_last=doe

{
  "datafinder": {
    "version": "2.0",
    "query-id": "510c7f5fa724fd3f86aadaa5e302bce2",
    "results": [
      {
        "#RawMatchCodes": "LF,P0",
        "#NormalizedRawScore": 100,
        "EmailAddr": "jdoe@gmail.com",
        "Phone": "5555555555",
        "Address": "555 10th st",
        "City": "Seattle",
        "State": "WA",
        "Zip": "98055",
        "Zip4": "4988",
        "@EmailAddr": "jdoe@aol.com (20171211)|j.doe@yahoo.com (20171114)",
        "@Phone": "5555551123 (20171211)|5555551124 (20170101)",
        "@FullAddr": "111 20TH PL W, Seattle WA, 98055 (20120809)",
      }
    ],
    "input-query": {
        "FirstName": "John",
        "LastName": "Doe",
        "Phone": "5555555555"
    },
    "num-results": 1,
    "query-time": "0.453",
    "page-time": "2.364"
  }
}