Hygiene and Lead Validation Overview

Hygiene and Lead Validation API Documentation

Datafinder's Hygiene and Lead Validation API service allows you to properly clean, format and validate your consumer contact data through a simple-to-use RESTful API. This documentation explains what are the expected inputs and outputs for the API service.

For a full feature list, please see the product page.

Request URL


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

Parameters


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 "clean" in this case. Yes
output Specify "json" or "xml" for output response type. Default is json.
Example:output=json

Input Contact Parameters

Any parameter that begins with a "d_" is a input contact parameter that cleaning and validation will be performed on. For this API product, d_last and d_first or d_fullname are required. If a contact parameter requires another, it will be noted in the table below.

NOTE: d_first and d_last are required for the Hygiene and Lead Validation API.

Name Description Required?
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_ip
Example:d_first=john
Yes
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_ip
Example:d_last=Doe
Yes
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_ip
Example:d_fullname=John Doe
Either this or d_first and d_last are required
Yes
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,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
Example: d_email=account_name@domain.com
 

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
  • page-time - how long the lookup took
  • errors - any error messages

Fields returned for each records in the "results":

Name Description Values
RecordUpdated Wether the hygiene system modifed the input values. YES or blank
Title Title ex: Mrs
FirstName First name ex: Larry
MiddleName Middle name ex: Bob
LastName Last name ex: Johnson
Suffix Suffix ex: III
BusName If the input record was a business, the name of the business ex: Versium
Phone A 10 digit phone number ex: 2065558739
Address A house number and street ex: 123 19th PL E
City City ex: Seattle
State Two digit state code ex: WA
Zip 5 digit zip code ex: 98055
EmailAddr Email address ex: joe@domain.com
Latitude Latitude ex: 29.2281192
Longitude Longitude ex: -127.1029938
ValidAddress Boolen indicator that specifies whether we found input address in our data sources YES or NOT FOUND
AddressMatchesFullName Boolean indicator that specifies whether we found the input name and address together in our data sources YES OR NOT FOUND
AddressMatchesLastName Boolean indicator that specifies whether we found the input last name and address together in our data sources YES or NOT FOUND
PhoneMatchesFullName Boolean indicator that specifies whether we found the input name and phone together in our data sources YES or NOT FOUND
PhoneMatchesLastName Boolean indicator that specifies whether we found the input last name and phone together in our data sources YES or NOT FOUND
PhoneMatchesAddress Boolean indicator that specifies whether we found the input phone and address together in our data sources YES or NOT FOUND
EmailMatchesLastName Boolean indicator that specifies whether we found the input last name and email together in our data sources YES or NOT FOUND
NameCategory Flag indicating whether the input record was for a consumer or buiness INDIVIDUAL or BUSINESS
LineType The input phone number line type MOBILE, UNKNOWN TYPE, VOIP
AreaCodeAndPrefixValid Flag indicating whether the area code and prefix of the input phone number are valid VALID or INVALID
PhoneValid Flag indicating whether the input phone number is valid VALID or INVALID
EmailAddressValid Flag indicating whether the input email address is valid VALID or INVALID

Output schema in JSON:

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

Example Queries and Response


Clean and validate contact information using a phone, address and first/last name:

https://api.datafinder.com/v2/qhv.php?k2=key&service=clean&d_phone=4255555095&d_first=jane&d_last=doe&d_fulladdr=123+18TH+PL+W&d_zip=98055&d_city=seattle&d_state=wa

                               
{
  "datafinder": {
    "version": "2.0",
    "query-id": "52b529b78d7de9effad131a76c8cf846",
    "results": {
      "Title": "",
      "FirstName": "JANE",
      "MiddleName": "",
      "LastName": "DOE",
      "Suffix": "",
      "Phone": "4255555095",
      "Address": "123 18TH PL W",
      "City": "SEATTLE",
      "State": "WA",
      "Zip": "98055",
      "Latitude": "47.822363",
      "Longitude": "-122.249135",
      "RecordUpdated": "",
      "ValidAddress": "YES",
      "AddressMatchesFullName": "YES",
      "AddressMatchesLastName": "YES",
      "PhoneMatchesFullName": "YES",
      "PhoneMatchesLastName": "YES",
      "PhoneMatchesAddress": "YES",
      "NameCategory": "INDIVIDUAL",
      "LineType": "UNKNOWN TYPE",
      "AreaCodeAndPrefixValid": "VALID",
      "PhoneValid": "YES",
      "ValidationScore": "88"
    },
    "input-query": {
      "FirstName": "jane",
      "LastName": "doe",
      "Address": "123 18TH PL W",
      "City": "seattle",
      "State": "wa",
      "Zip": "98055",
      "Phone": "4255555095"
    },
    "page-time": 1.1558120250702
  }
}