Contact Validation API
Description
Standardizes, corrects, and completes contact data, verifies postal address, confirms the name associated with the address, and appends Gender and DOB. If enabled, will also append optional demographics.
Actions Performed
The following validation and enhancement actions will be applied to the input data:
Formatting:
- Phone numbers
- Standardized 10-digit format
- Postal addresses
- Standardized single line address
- Proper casing
- 2-digit state code
- Zip code +4
- Email
- To lower case
Proper Casing:
- Names, addresses, city, state and email
Auto-Correction:
- Correct misspellings in names and addresses
- Correct typos in email (i.e. gmaill.com -> gmail.com)
Appends:
- Gender
- DOB (Month + Year)
- DOD (Date of Death)
- Missing city, state or zip
- Postal address moves (optional)
- When demographics appending is enabled:
- One or more of: Children Age Range, Education, Household Size, Political Party, Presence Of Senior, Credit Card User, Ethnic Code, Ethnic Group, Household Income, Marital Status, Length Of Residence, Presence Of Children, Occupation, Homeowner or Renter
Validation:
- Postal address is valid to building or unit level.
- Postal address is deliverable by USPS or third-party service.
- Name and address match the data on record.
Request URL
https://api.rrdblive.com/DDM/WebService.cfc?method=process
Supported HTTP methods: GET or POST
Authentication Parameters
| ClientID | Your "Client ID" |
| CWSID | Your "Client Web Service ID" |
| Token | A token that is authorized to process this web service request |
Required Parameters
At least one of the following fields (or combinations) are required:
| MailAddress1 | Contact's street address |
| PostalZipCode | Contact's zip code |
| AND/OR | |
| PhoneNumber | Contact's phone number |
| AND/OR | |
| EmailAddress | Contact's email address |
Optional Parameters
| FirstName | Contact's first name |
| MiddleName | Contact's middle name |
| LastName | Contact's last name |
| MailAddress2 | Contact's street address line 2 (if applicable) |
| CityName | Contact's city name |
| ProvinceStateName | Contact's state name or code |
| CountryName | Contact's country name or code |
Parameters may be passed as either URL query parameters or posted as FORM fields
Response JSON
{
"success": true,
"errors": [],
"dataIn": [
{
"FirstName": "",
"MiddleName": "",
"LastName": "",
"MailAddress1": "",
"MailAddress2": "",
"CityName": "",
"ProvinceStateName": "",
"PostalZipCode": "",
"CountryName": "",
"PhoneNumber": "",
"EmailAddress": ""
}
],
"dataOut": [
{
"BirthDate": "",
"CityName": "",
"CountryName": "",
"DateOfDeath": "",
"EmailAddress": "",
"FirstName": "",
"Gender": "",
"LastName": "",
"MailAddress1": "",
"MailAddress2": "",
"MiddleName": "",
"MoveDate": "",
"PhoneNumber": "",
"PostalAddressIsValid": "",
"PostalAddressIsValidMissingSuite": "",
"PostalAddressNameMatch": "",
"PostalZipCode": "",
"ProvinceStateName": ""
}
]
}
Response Keys
| Key | Description |
|---|---|
| success | "true" if request was successful / "false" if errors occurred |
| errors | If "success" was "false", will contain an array of error objects. See below for sample error response. |
| dataIn | The original input data |
| dataOut | If "success" was "true", will return the validation results |
"dataOut" Fields
| Name | Description |
|---|---|
| BirthDate | Date of birth in the format YYYYMM01 |
| CityName | Standardized city name |
| CountryName | 2-digit country code |
| DateOfDeath | Date of death in the format YYYYMMDD |
| EmailAddress | Standardized email address |
| FirstName | Standardized first name |
| Gender | Gender based on name & demographics (M, F, N, U) |
| LastName | Standardized last name |
| MailAddressLine1 | Standardized single address line |
| MailAddressLine2 | Line 2 of address if it could not be standardized to single line |
| MiddleName | Standardized middle name |
| MoveDate | Date associated with the move address (if applicable) |
| PhoneNumber | Standardized phone number |
| PostalAddressIsValid | 0 = The postal address is invalid or NOT deliverable 1 = The postal address is verified and deliverable |
| PostalAddressIsValidMissingSuite | 0 = N/A 1 = Building address is valid, but suite/apt number is missing |
| PostalAddressNameMatch | 0 = The name does NOT match the postal address 1 = The name matches the postal address (first or last) |
| PostalZipCode | Standardized zip code + 4 |
| ProvinceStateName | Standardized state code |
Demographic Appends
If appending select demographics, the values will be returned as follows:
| Name | Values |
|---|---|
| ChildrenAgeRange | 0-2 3-5 6-10 11-15 16-17 NOTE: Will return a list if more than one range applies |
| CreditCardUser | Yes No |
| Education | High School College Graduate School Vocational/Technical School |
| EthnicCode | See below for "All Ethnic Code Values" |
| EthnicGroup | Southeast Asian Central & Southwest Asian Eastern European All African American Ethnic Groups Middle Eastern Jewish Mediterranean Native American Far Eastern Polynesian Scandinavian Other Western European Hispanic |
| HouseholdIncome | $0-$15,000 $15,001-$20,000 $20,001-$30,000 $30,001-$40,000 $40,001-$50,000 $50,001-$60,000 $60,001-$75,000 $75,001-$100,000 $100,001-$125,000 $125,001-$150,000 $150,001+ |
| HouseholdSize | 1 2 3 4 5 6 7 8 9 |
| LengthOfResidence | Less than 1 year 1-2 years 2-3 years 3-4 years 4-5 years 5-6 years 6-7 years 7-8 years 8-9 years 9-10 years 10-11 years 11-12 years 12-13 years 13-14 years 14-15 years 15+ years |
| MaritalStatus | Definitely Single Inferred Single Inferred Married Definitely Married |
| Occupation | Physician/Dentist Healthcare Lawyer/Judge Professional/Technical Management Teacher/Educator Sales/Marketing Clerical/Service Worker Tradesmen/Laborer Farmer Student Homemaker Retired Federal Employee Military Military Retired Business Owner Religious Self Employed Financial Other |
| OwnRent | Definite Renter Inferred Renter Inferred Owner Definite Owner |
| PoliticalParty | No Party Republican Democrat Independent |
| PresenceOfChildren | No Children Present Children Present |
| PresenceOfSenior | No Senior Present Senior Present |
| All Ethnic Code Values | ||
|---|---|---|
Afghan African-American Albanian Aleutian Algerian American Indian Arabian Armenian Ashanti Australian Austrian Azerbaijani Bahrain Bangladesh Basotho Basque Belgian Belorussian Beninese Bhutanese Black African Bosnian Muslim Botswanian Bulgarian Burkina Faso Burundian Cameroonian Caribbean African American Central African Republic Chadian Chechnyan Chinese Comoros Congolese Croatian Czech Danish Djiboutian Dutch Egyptian English Equatorial Guinea Estonian Ethiopian Fiji Finnish French Gabon Gambian Georgian German Ghanaian |
Greek Guinea Bissau Guinean Guyanese Hausa Hawaiian Icelandic Indian Indonesian Iraqi Irish Italian Ivorian Japanese Jewish Kampuchean/Khmer(Cambodian) Kazakhstan Kenyan Kirghizia Korean Kurdish Kuwaiti Kyrgyzstani Laotian Latvian Lesotho Liberian Libyan Liechtenstein Lithuanian Luxembourgian Macedonia Madagascan Malawian Malaysian Maldivian & Tongan Malian Maltese Manx Mauritanian Moldovan Mongolian Moroccan Mozambican Multi-Ethnic Myanmar (Burmese) Namibian Nepalese New Zealand Niger Nigerian Norwegian |
Other Oriental Pakistani Papua New Guinean Persian Philippine Pili Polish Portuguese Qatari Romanian Russian Saudi Scottish Senegalese Serbian Seychelles Sierre Leone Sinhalese (Sri-Lankan) Slovakian Slovenian Somalian South African Spanish Sudanese Surinamese Swedish Swiss Syrian Tajik Tajikistan Tanzanian Telugan Thai Tibetan Togolese Tonga Tunisian Turkish Turkmenistan Ugandan Ukrainian Uzbekistan Vanuatuan Vietnamese Welsh Western Samoan Xhosa Yemeni Zairean Zambian Zimbabwean Zulu |
Sample Error Response JSON
{
"success": false,
"errors": [
{
"errorID": 1000,
"errorHeader": "Authentication Failed",
"errorMessage": "API user access denied"
}
]
}
4xx HTTP Status Code will be returned for all of the following:
| errorID | errorHeader | errorMessage |
|---|---|---|
| 400 | API Error | Depends on the cause of error |
| 403 | API Error | This API supports HTTPS only |
| 500 | Unexpected Error | Depends on the cause of error |
| 1000 | Authentication Failed | Depends on the cause of error |
| 2000 | Validation Error | Required fields are missing or blank |
| 35030 | Web Service Error | Active web service was not found |
| 35040 | Web Service Error | The supplied Token is not authorized for use with this CWSID |
| 35050 | Web Service Error | No data was submitted |
| 35060 | Web Service Error | Depends on the cause of error |
| 35070 | Web Service Error | This web service supports only one record at a time |