Predictive Scores Append Documentation

Predictive Scores Append API Overview

Datafinder's Predictive Scores Append API service enables you to programmatically score and sort your leads by popular metrics such as a person's wealth, propensity to give, propensity to be green, and more.

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=scores&dcfg_scores={score}


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.
Example: cfg_mc=LF,ACSZ
For a list of all match codes, see the Match Codes page.
dcfg_scores A comma separated list of the scores you would like returned. PLEASE NOTE: you will be charged PER SCORE returned.
Example: dcfg_scores=GreenScoreNorm,WealthScoreNorm

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

Predictive Scores Options

These are scores you may retrieve through the Predictive Scores API. Enter them as a comma separated list in the dcfg_scores parameter.

NOTE: You will be charged PER SCORE returned. Please see the API pricing chart for a further explanation of the pricing.

Name Description
WealthScoreNorm Measure of wealth
DonorScoreNorm Propensity to give charitable donations
GreenScoreNorm Propensity to be environmentally aware and make green decisions
AutoFinanceScoreNorm Propensity and ability to finance a vehicle
DIYScoreNorm Measure of interest someone has in working on DIY tasks
TravelScoreNorm Propensity to travel for leisure or business
NewTechAdopterScoreNorm Propensity to purchase new technologies
OnlineShopperScoreNorm Propensity to purchase items online

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
_RawScore Represents how close the match is.
_WeightedScore Weighted score that represents how close the match is.
_RawMatchCodes See the Match Codes page
FirstName A first name
MiddleName A middle name
LastName A last name
Address A street address
City A city
State A state
Zip A zip
Phone A phone number
WealthScoreNorm Integer between 1 and 100
DonorScoreNorm Integer between 1 and 100
GreenScoreNorm Integer between 1 and 100
AutoFinanceScoreNorm Integer between 1 and 100
DIYScoreNorm Integer between 1 and 100
TravelScoreNorm Integer between 1 and 100
NewTechAdopterScoreNorm Integer between 1 and 100
OnlineShopperScoreNorm Integer between 1 and 100

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",
        "GreenScoreNorm": "54",
        "DonorScoreNorm": "75",        
    "input-query": {
      "Phone": "5555555555"
    "num-results": 1,
    "query-time": "0.453",
    "page-time": "2.364"