DOTS Lead Validation International is easily our most robust and valuable service. This service improves the quality of your leads by correcting or eliminating unreliable contact record data while providing you with an overall quality score, so you can make informed business decisions. This service cross-references prospects’ name, address, phone, email, and IP address to ensure the lead information is genuine, accurate and up-to-date.
The quality of each of these data points is analyzed and scored separately and also combined to provide a weighted composite score for the overall lead quality and certainty. These individual and composite scores are included in the fifty-plus outputs the service provides, allowing you to tailor business logic to meet your needs.
Lead Validation International can be used like our other services; as a real-time API, as a cloud connector for major CRMs and marketing automation platforms, or as an FTP service. If none of these work for you, you can send us your list and we will validate and correct the leads for you.
Customizing Lead Validation International to Meet Your Needs
Even if you are missing some of the contact record data points (e.g., email, phone, address, name, or IP) that the service uses to validate leads, our service can be customized to use the data you do have, correct any issues with it and provide certainty scores. To customize our service to work with your available data, we suggest using the variable, TestType. There are a number different test types that address common variations of available data points and the needs of our clients. These test types can be further configured to meet the specific needs of your application and business. If you are not sure about what test type you should use, please don’t hesitate to reach out, we will gladly help with best recommendations. We are committed to making sure you receive the full benefit and power of our Lead Validation International service, and if none of the available test types meet your needs, we are happy to create custom ones that will.
Interpreting API Responses
Interpreting the response from our API is an important first step in determining the best ways to use the service and how the resulting validated data can benefit your business. There are only three “required” inputs to Lead Validation International: Country, TestType, and LicenseKey. If all three of these inputs are provided, Lead Validation International will attempt to process all the lead information that is present. If the required inputs are not provided, here are some of the errors you might encounter:
- Error Code 1 – Authorization Codes
These errors indicate there is something wrong with the license key and we recommend that you double check you are using the correct key. One of the most common causes for this type of error is using a test key in a live environment (or vice-versa). Fortunately, this type of error is simple to detect and correct. In the test environment, the request URL should start with “https://trial.serviceobjects…” and be used with the test key sent to you. Production keys and URLs are different and issued only to customers. For other errors, please do not hesitate to reach out to us to help troubleshoot.
| Error Description Code | Error Description | Additional Description |
|---|---|---|
| 1 | Please provide a valid license key for this web service. | There was no license key submitted to the service. Often, this occurs when the URL encoding has not occurred correctly. |
| 2 | The daily allowable number of transactions for this license key has been exceeded. | This does not apply to all keys, but some have a daily maximum transactions limit. |
| 3 | The monthly allowable number of transactions for this license key has been exceeded. | Some keys have a monthly maximum. You will encounter this value if you pass the monthly maximum. |
| 4 | The total allowable number of transactions for this license key has been exceeded. | The overall amount of transactions has been exceeded. |
- Error Code 2 – User Input
Something is wrong with the inputs. Either necessary fields were left blank, or the inputs entered are too long.
| Error Description Code | Error Description | Additional Description |
|---|---|---|
| 1 | That does not appear to be a valid TestType. | The given test type was either blank or an invalid test type. Please contact us to help assist with a test type that would suit your needs. |
| 2 | The Country input is missing. | There was no value in the Country field of the input. This is a required field that allows the service to cross reference different data points. |
- Error Code 3 – Fatal Errors
This unlikely error indicates that the web service is behaving in an unexpected way. If you see this error in a production environment, please notify Service Objects at once.
| Error Description Code | Error Description | Additional Description |
|---|---|---|
| 1 | Unhandled error. Please contact Service Objects. | Like it says, please contact Service Objects immediately and let us know what inputs you used to create this error. |
- Error Code 4 – Domain Specific
Some of our other services return Domain Specific errors which indicate the validity or lack thereof of the information sent to the service. Lead Validation International works a bit differently since it is a composite service and cross-checks data points to provide an overall score for the lead. Currently, there are no Domain Specific errors in our Lead Validation International service.
Validated International Lead Outputs
If everything is working as expected, the service will return over fifty outputs including validated and corrected data, quality scores and any additional notes that might be helpful. The table below shows the most common outputs and a brief description of what they mean.
| Return Value | Description |
|---|---|
| OverallCertainty | This is the total lead score. It represents how likely it is that the given lead is valid. 100 is the best score, and 0 is the worst. |
| OverallQuality | There are only three different values that can be returned for this field: Reject, Review or Accept. This is a quick and easy flag that can be used to identify the overall quality of the lead. If necessary, separate reject, review, and accept flags can be developed internally. |
| LeadType | Provides a classification that helps flag the type of lead given. Values will be Residential, Business, or Unknown. |
| LeadCountry | The country associated with the given lead. It is presented in ISO2 format. |
| NoteCodes | These will be an enumerated list of the overall codes associated with the lead. These note nodes will provide further information about the quality of the lead and the different data points that did or did not match up. As a general rule, NoteCodes that are lower than 100 are marks against a lead and notes higher than 100 are data points that indicate cross data matching in the lead. |
| NoteDesc | These will be the descriptions that are associated with the NoteCodes. |
| NameScore | This is the first of the different component scores that Lead Validation International provides. Along with an overall certainty score, Lead Validation International will provide a score for each of the different pieces of information given as inputs. This field ranges from 0 to 100 and indicates the probability that the given data name is valid. |
| NameQuality | Values will be Reject, Review or Accept. A quick and easy flag to accept or reject the name portion of the lead. |
| FirstName | The first name without diacritic (i.e., accented) characters. |
| LastName | The parsed out last name of the lead. |
| FirstNameClean | The first name without diacritic (i.e., accented) characters. |
| NameNoteCodes | An enumerated list of note codes that provide further information on the quality of the name. |
| NameNoteDesc | The text-based descriptions associated with the codes in the previous field. |
| AddressScore | The overall score of the address portion of the lead. It ranges from 0 to 100. |
| AddressQuality | A simple reject, review or accept flag indicating the quality of the address portion. |
| Address1 | The validated Address1 line of the input address. |
| Address2 | The validated Address2 line of the input address. |
| Address3 | The validated Address3 line of the input address. |
| Address4 | The validated Address4 line of the input address. |
| Address5 | The validated Address5 line of the input address. |
| AddressLocality | The locality associated with the given input address. This is typically the City of the address. |
| AddressAdminArea | The Administrative Area associated with the input address. Typically corresponds to the State or province of an address. |
| AddressPostalCode | Validated postal code of the input address. |
| AddressCountry | Validated country associated with the input address. |
| AddressResolutionLevel | The resolution level to which the input address could be resolved. This will give some information on whether there is DPV, premise, or other data available for an address. |
| AddressNoteCodes | An enumerated list of codes that provide more information on the quality of an address. |
| AddressNoteDesc | Descriptive notes that correspond to the note codes for this field. |
| EmailScore | A score between 0 and 100 that ranks the validity of the given email address. |
| EmailQuality | A reject, review or accept flag that gives a simple flag on the quality of the input email address. |
| EmailCorrected | A True or False flag that indicates whether or not the input email address was corrected. |
| EmailNoteCodes | An enumerated list of codes that provide more information about the quality of the email address. |
| EmailNoteDesc | Descriptive notes that correspond to the note codes. |
| IPAddressScore | A score between 0 and 100 representing the validity of the given IP address. |
| IPAddressQuality | A simple reject, review and accept flag that will highlight the validity of the IP address portion of the lead. |
| IPCountry | The country associated with the IP Address. |
| IPLocality | The locality associated with the IP Address. |
| IPAdminArea | The Administrative area associated with the IP Address. |
| IPNoteCodes | An enumerated list of note codes that provide additional information about the quality of the IP address. |
| IPNoteDesc | Descriptive notes that correspond to the note codes. |
| Phone1Score | A simple reject, review, or accept flag that that indicates the quality of the given phone number. |
| Phone1Quality | A Simple reject, review or accept flag that that indicates the quality of the given phone number. |
| Phone1Locality | The Locality associated with the Phone1 field. |
| Phone1AdminArea | The Admin Area associated with the Phone1 field. |
| Phone1Country | The Country associated with the Phone1 field. |
| Phone1NoteCodes | An enumerated list of note codes that provide additional information about the quality of the Phone Number. |
| Phone1NoteDesc | Descriptive notes that correspond to the codes in the previous fields. |
| Phone2Score | A score between 0 and 100 that indicates the validity of the phone number in the Phone2 field. |
| Phone2Locality | A simple reject, review or accept flag that that indicates the quality of the given phone number. |
| Phone2Locality | The Locality associated with the Phone2 field. |
| Phone2AdminArea | The Admin Area associated with the Phone2 field. |
| Phone2Country | The Country associated with the Phone2 field. |
| Phone2NoteCodes | An enumerated list of note codes that provide additional information about the quality of the Phone Number. |
| Phone2NoteDesc | Descriptive notes that correspond to the codes in the previous fields. |
| PhoneContact | A Phone Contact Object. We will list this below. |
| InformationComponents | An array of information components. These are key-value pairs that can allow us to additional outputs and features to Lead Validation in the future. |
When available, Lead Validation International can return the contact name and address information associated with the phone number.
| Name | Name associated with the phone number. |
| Address | Address associated with the phone number. |
| City | City associated with the phone number. |
| State | State associated with the phone number. |
| Zip | Zip Code associated with the input address. |
| Type | Indicates the phone contact type. Returns can be Residential, Business or Unknown. |
Hopefully, this quick primer is the first step to developing a better understanding of our Lead Validation International service and how it can be applied to your needs. Please reach out to us with any questions, and we will gladly provide recommendations, integration assistance or any other help you may need.
