Anatomy of a Service: DOTS Lead Validation International

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:

  1. 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 DescriptionAdditional Description
1Please 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.
2The 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.
3The 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.
4The total allowable number of transactions for this license key has been exceeded.The overall amount of transactions has been exceeded.

 

  1. 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 CodeError DescriptionAdditional Description
1That 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.
2The 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.

 

  1. 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 CodeError DescriptionAdditional Description
1Unhandled 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.

 

  1. 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
  OverallCertaintyThis 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.
  OverallQualityThere 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.
  LeadTypeProvides a classification that helps flag the type of lead given. Values will be Residential, Business, or Unknown.
  LeadCountryThe country associated with the given lead. It is presented in ISO2 format.
  NoteCodesThese 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.
  NoteDescThese will be the descriptions that are associated with the NoteCodes.
  NameScoreThis 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.
  NameQualityValues will be Reject, Review or Accept. A quick and easy flag to accept or reject the name portion of the lead.
  FirstNameThe first name without diacritic (i.e., accented) characters.
  LastNameThe parsed out last name of the lead.
  FirstNameCleanThe first name without diacritic (i.e., accented) characters.
  NameNoteCodesAn enumerated list of note codes that provide further information on the quality of the name.
  NameNoteDescThe text-based descriptions associated with the codes in the previous field.
  AddressScoreThe overall score of the address portion of the lead. It ranges from 0 to 100.
  AddressQualityA simple reject, review or accept flag indicating the quality of the address portion.
  Address1The validated Address1 line of the input address.
  Address2The validated Address2 line of the input address.
  Address3The validated Address3 line of the input address.
  Address4The validated Address4 line of the input address.
  Address5The validated Address5 line of the input address.
  AddressLocalityThe locality associated with the given input address. This is typically the City of the address.
  AddressAdminAreaThe Administrative Area associated with the input address. Typically corresponds to the State or province of an address.
  AddressPostalCodeValidated postal code of the input address.
  AddressCountryValidated country associated with the input address.
      AddressResolutionLevelThe 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.
  AddressNoteCodesAn enumerated list of codes that provide more information on the quality of an address.
  AddressNoteDescDescriptive notes that correspond to the note codes for this field.
  EmailScoreA score between 0 and 100 that ranks the validity of the given email address.
  EmailQualityA reject, review or accept flag that gives a simple flag on the quality of the input email address.
  EmailCorrectedA True or False flag that indicates whether or not the input email address was corrected.
  EmailNoteCodesAn enumerated list of codes that provide more information about the quality of the email address.
  EmailNoteDescDescriptive notes that correspond to the note codes.
  IPAddressScoreA score between 0 and 100 representing the validity of the given IP address.
  IPAddressQualityA simple reject, review and accept flag that will highlight the validity of the IP address portion of the lead.
  IPCountryThe country associated with the IP Address.
  IPLocalityThe locality associated with the IP Address.
  IPAdminAreaThe Administrative area associated with the IP Address.
  IPNoteCodesAn enumerated list of note codes that provide additional information about the quality of the IP address.
  IPNoteDescDescriptive notes that correspond to the note codes.
  Phone1ScoreA simple reject, review, or accept flag that that indicates the quality of the given phone number.
  Phone1QualityA Simple reject, review or accept flag that that indicates the quality of the given phone number.
  Phone1LocalityThe Locality associated with the Phone1 field.
  Phone1AdminAreaThe Admin Area associated with the Phone1 field.
  Phone1CountryThe Country associated with the Phone1 field.
  Phone1NoteCodesAn enumerated list of note codes that provide additional information about the quality of the Phone Number.
  Phone1NoteDescDescriptive notes that correspond to the codes in the previous fields.
  Phone2ScoreA score between 0 and 100 that indicates the validity of the phone number in the Phone2 field.
  Phone2LocalityA simple reject, review or accept flag that that indicates the quality of the given phone number.
  Phone2LocalityThe Locality associated with the Phone2 field.
  Phone2AdminAreaThe Admin Area associated with the Phone2 field.
  Phone2CountryThe Country associated with the Phone2 field.
  Phone2NoteCodesAn enumerated list of note codes that provide additional information about the quality of the Phone Number.
  Phone2NoteDescDescriptive notes that correspond to the codes in the previous fields.
  PhoneContactA Phone Contact Object. We will list this below.
  InformationComponentsAn 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.

Ready to Get Started?
Subscribe to our blog