Consumer Contact Append Documentation

Consumer Contact Append Overview

Datafinder's Consumer Contact Append API service enables you to programmatically append complete contact information to your customer or prospect list. Fill in the missing contact information such as full names, 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.

Request URL{your-key}&service={phone-or-email-or-address}


Config Parameters

Use the config parameters to adjust elements like the output language.

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.
cfg_cutoffdate Do not return records which have a timestamp OLDER than YYYYMMDD. For example, if one wanted records that were from 2012 or later, use 20120000
cfg_cutoffmaxdate Do not return records with a timestamp NEWER than YYYYMMDD
dcfg_emailinvalid Currently the Datafinder forward email append api will only show results if the email address being appended is valid. Set dcfg_emailinvalid to 1 in order to also show results where the email address is invalid.
Example: dcfg_emailinvalid=1
This parameter only applies to the Email Append API.

Search Parameters

Any parameter that begins with a "d_" is a search parameter. We will use these parameters to try and match an individual or household. Some search parameters will not return results if used by themselves, such as d_last or d_first. If a search parameter requires another, it will be 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_email or d_phone or d_fulladdr, d_city, d_state or d_fulladdr,d_zip or d_dob or d_lat,d_long
d_last A last name.
Requires: d_email or d_phone or d_fulladdr, d_city, d_state or d_fulladdr,d_zip or d_dob or d_lat,d_long
d_fullname A first and last name.
Requires: d_email or d_phone or d_fulladdr, d_city, d_state or d_fulladdr,d_zip or d_dob or d_lat,d_long
Example:d_fullname=john smith
d_zip A 5 digit zip code in the USA.
Requires: d_fulladdr
d_fulladdr Entire house number + street + suite (e.g. "7530 164th Ave NE, Ste A204")
Requires: d_city,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,d_city or d_fulladdr,d_zip
Example: d_state=CO
d_phone Ten digits NPANXXNNNN
Example: d_phone=8003950164
d_email Valid email address
d_lat,d_long latitude / longitude
Example: d_long=74.0059,d_lat=40.7127

Output Fields

Api results will follow the schema shown below and will 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 records in the "results":

Name Description Service
_RawScore Represents how close the match is. email, phone, address
_WeightedScore Weighted score that represents how close the match is. email, phone, address
_RawMatchCodes See the Match Codes page email, phone, address
TimeStamp The date and time at which the data for this data was saved. email, phone, address
FirstName A first name email, phone, address
MiddleName A middle name email, phone, address
LastName A last name email, phone, address
Address A street address email, phone, address
City A city email, phone, address
State A state email, phone, address
Zip A zip email, phone, address
Phone A phone number phone
LineType The line type of the phone number. NOTE: Due to factors like number portability, there is up to a 10% inaccuracy with the LineType result. phone
EmailAddr An email address email
EmailAddrUsable Returns a "YES" if this is a valid email address. email

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

  "datafinder": {
    "version": "2.0",
    "query-id": "510c7f5fa724fd3f86aadaa5e302bce2",
    "results": [
        "#RawScore": 25,
        "#WeightedScore": 25,
        "#RawMatchCodes": "P0",        
        "FirstName": "John",
        "MiddleName": "J",
        "LastName": "Doe",
        "Address": "555 10th st",
        "City": "Seattle",
        "State": "WA",
        "Zip": "98055",
        "Zip4": "4988",
        "Phone": "5555555555",
        "TimeStamp": "20131200",        
        "LineType": "Landline"
    "input-query": {
      "Phone": "5555555555"
    "num-results": 1,
    "query-time": "0.453",
    "page-time": "2.364"