LV – ValidateLead_V3 – Recommended Operation

Our Lead Validation service cross-validates, corrects and scores over 130 key data points to help your business more accurately identify quality leads for US and Canada. Works with leading CRM and marketing automation platforms.

This document defines the input, output, and behavior of the web services in LV.

Important Note!

Lead Validation cannot determine the complete validity of a lead 100% of the time. Often, unlisted phone numbers, cell phone numbers, very rare names, rural or new addresses, and the like will cause either neutral or negative shifts in a lead’s validity. LV provides a baseline guide of a lead’s quality that must be taken with serious consideration.

URL Endpoints

JSON:
- https://trial.serviceobjects.com/lv/api.svc/JSON/ValidateLead_V3?FullName={FULLNAME}&Salutation={SALUTATION&FirstName={FIRSTNAME}&LastName={LASTNAME}&BusinessName={BUSINESSNAME}&BusinessDomain={BUSINESSDOMAIN}&BusinessEIN={BUSINESSEIN}&Address1={ADDRESS1}&Address2={ADDRESS2}&Address3={ADDRESS3}&Address4={ADDRESS4}&Address5={ADDRESS5}&Locality={LOCALITY}&AdminArea={ADMINAREA}&PostalCode={POSTALCODE}&Country={COUNTRY}&Phone1={PHONE1}&Phone2={PHONE2}&Email={EMAIL}&IPAddress={IPADDRESS}&Gender={GENDER}&DateOfBirth={DATEOFBIRTH}&UTCCaptureTime={UTCCAPTURETIME}&OutputLanguage={OUTPUTLANGUAGE}&TestType={TESTTYPE}&LicenseKey={LICENSEKEY}

XML:
- https://trial.serviceobjects.com/lv/api.svc/XML/ValidateLead_V3?FullName={FULLNAME}&Salutation={SALUTATION&FirstName={FIRSTNAME}&LastName={LASTNAME}&BusinessName={BUSINESSNAME}&BusinessDomain={BUSINESSDOMAIN}&BusinessEIN={BUSINESSEIN}&Address1={ADDRESS1}&Address2={ADDRESS2}&Address3={ADDRESS3}&Address4={ADDRESS4}&Address5={ADDRESS5}&Locality={LOCALITY}&AdminArea={ADMINAREA}&PostalCode={POSTALCODE}&Country={COUNTRY}&Phone1={PHONE1}&Phone2={PHONE2}&Email={EMAIL}&IPAddress={IPADDRESS}&Gender={GENDER}&DateOfBirth={DATEOFBIRTH}&UTCCaptureTime={UTCCAPTURETIME}&OutputLanguage={OUTPUTLANGUAGE}&TestType={TESTTYPE}&LicenseKey={LICENSEKEY}

ValidateLead_V3 Inputs

TestType and LicenseKey are the only required inputs, if they are missing or incorrect ValidateLead_V3 will throw an error. All other inputs are optional, but missing key data without a test type that accounts for it could cause tests to fail and potentially greatly impact the resulting score. (e.g. Omitting Name will cause all name tests to fail as well as name to email tests, name to phone tests, etc…)

Name	Type	Length	Description
FullName	String	60	The contact’s full name. e.g. Jane Doe
Salutation	String	10	Salutation of the contact. Dr, Esq, Mr, Mrs etc
FirstName	String	60	First name of the contact. e.g. Jane
LastName	String	60	Last name of the contact. e.g. Doe
BusinessName	String	60	The contacts company. e.g. Service Objects
BusinessDomain	String	60	Website domain associated with the business. e.g. serviceobjects.com
BusinessEIN	String	60	Represents the Company Tax Number. Used for Tax exempt checks for US leads.
Address1	String	60	The address 1 of the contact or business address.
Address2	String	60	The address 2 of the contact or business address.
Address3	String	60	The address 3 of the contact or business address.
Address4	String	60	The address 4 of the contact or business address.
Address5	String	60	The address 5 of the contact or business address.
Locality	String	60	The city of the contact’s postal address.
AdminArea	String	60	The state of the contact’s postal address.
PostalCode	String	20	The zip code of the contact’s postal address.
Country	String	60	The country of the contact’s postal address. e.g. United States, US or USA
Phone1	String	20	The contact’s primary phone number.
Phone2	String	20	The contact’s secondary phone number.
Email	String	60	The contact’s email address.
IPAddress	String	45	The contact’s IP address in IPv4. (IPv6 coming in a future release)
Gender	String	10	Male, Female or Neutral
DateOfBirth	String	10	The contact’s date of birth
UTCCaptureTime	String	10	The time the lead was submitted
OutputLanguage	String	20	Language field indicating what language some of the output information will be.
TestType ^[1]	String	20	The name of the type of validation you want to perform on this contact.
LicenseKey	String	20	Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/lead-validation/

ValidateLead_V3 Outputs

All of the response objects are contained within the ValidateLead_V3 object.

Name	Type	Length	Values	Description
OverallCertainty	string	3	Varies	A value that represents the overall certainty that the service provided on the lead. This value will range from 0 to 100.
OverallQuality	string	10	Reject, Review or Accept	A field indicating whether the lead should be rejected, reviewed or accepted
LeadType	string	10	Residential, Business or Unknown	Indicates the classification that the service made for the lead.
LeadCountry	string	3	Varies	The country associated with the lead, given as an ISO 2.
NoteCodes	string	–	Varies	Enumerated list of descriptive notes
NoteDesc	string	–	Varies	Descriptions that correspond to the NoteCodes section
NameCertainty	string	3	Varies	Score between 0 and 100 that indicates the probability that the given name is valid.
NameQuality	string	10	Reject, Review or Accept	A field indicating whether the given name should be rejected, reviewed or accepted.
FirstName	string	60	Varies	The first name with diacritic characters.
LastName	string	60	Varies	The last name with diacritic characters.
FirstNameClean	string	60	Varies	The first name of the lead without diacritic characters.
LastNameClean	string	60	Varies	The last name of the lead without diacritic characters.
NameNoteCodes	string	–	Varies	Enumerated list of codes indicating further information about the name field.
NameNotesDesc	string	–	Varies	Enumerated list of descriptive notes that correspond to the NameNoteCodes field.
AddressCertainty	string	3	Varies	Score between 0 and 100 that indicates the validity of the given address.
AddressQuality	string	10	Reject, Review or Accept	A field indicating whether the given address should be rejected, reviewed or accepted
Address1	string	60	Varies	The validated Address line 1
Address2	string	60	Varies	The validated Address line 2
Address3	string	60	Varies	The validated Address line 3
Address4	string	60	Varies	The validated Address line 4
Address5	string	60	Varies	The validated Address line 5
AddressLocality	string	60	Varies	The locality associated with the given input address. Usually corresponds to the city.
AddressAdminArea	string	60	Varies	The Admin Area tied with the input address. Usually corresponds to the State or Province.
AddressPostalCode	string	20	Varies	The Postal Code tied to the given input address.
AddressCountry	string	60	Varies	2 Character ISO code for the country
AddressNoteCodes	string	–	Varies	Enumerated list of codes indicating additional information about the given address.
AddressNoteDesc	string	–	Varies	Enumerated list of descriptive notes that are associated with the AddressNoteCodes field.
EmailCertainty	string	3	Varies	Score between 0 and 100 that indicates the validity of a given email address
EmailQuality	string	10	Reject, Review or Accept	A field indicating whether the given email address should be rejected, reviewed or accepted
EmailCorrected	string	60	Varies	The email used for testing including any corrections that were made.
EmailNoteCodes	string	–	Varies	Enumerated list of codes indicating additional information about the given email address
EmailNoteDesc	string	–	Varies	List of descriptions associated with the EmailNoteCodes field.
IPAddressCertainty	string	3	Varies	Score between 0 and 100 that indicates the validity of a given IP address.
IPAddressQuality	string	10	Reject, Review or Accept	A field indicating whether the given IP address should be rejected, reviewed or accepted
IPCountry	string	60	Varies	Country ISO 2 code associated with the given IP address
IPLocality	string	60	Varies	The locality associated with the given IP address
IPAdminArea	string	–	Varies	Administrative area associated with the given IP address
IPNoteCodes	string	–	Varies	Enumerated list of codes indicating additional information about the given IP address
IPNoteDesc	string	–	Varies	Descriptions associated with the IPNoteCodes that indicate additional information about a given IP address
Phone1Certainty	string	3	Varies	Score between 0 and 100 that indicates the validity of the phone number in the Phone1 field.
Phone1Quality	string	10	Reject, Review or Accept	A field indicating whether the Phone1 input should be rejected, reviewed or accepted.
Phone1Locality	string	60	Varies	Locality associated with the given IP address
Phone1AdminArea	string	60	Varies	The administrative area associated with the given phone number.
Phone1Country	string	3	Varies	The Country ISO 2 code associated with the given phone number in the Phone1 field.
Phone1NoteCodes	string	–	Varies	Note codes containing additional
Phone1NoteDesc	string	–	Varies	Descriptions that correlate with the codes given in the Note Codes field
Phone2Certainty	string	3	Varies	Not currently used
Phone2Quality	string	10	Reject, Review or Accept	Not currently used
Phone2Locality	string	60	Varies	Not currently used
Phone2AdminArea	string	60	Varies	Not currently used
Phone2Country	string	3	Varies	Not currently used
Phone2NoteCodes	string	–	Varies	Not currently used
Phone2NoteDesc	string	–	Varies	Not currently used
PhoneContact	PhoneContact	–	Varies	The contact information associated with the phone number
InformationComponents	InformationComponent[]	–	Varies	An array of key value pairs that contain additional fields and information not defined in the original output schema of the API.
Error	Error	–	Varies	See “Errors“.

PhoneContact Type

Name	Type	Values	Description
Name	String	Varies	The contact’s full name.
Address	String	Varies	The contact’s postal address.
City	String	Varies	The city of the contact’s postal address.
State	String	Varies	The state of the contact’s postal address.
Zip	String	Varies	The zip code of the contact’s postal address.
Type	String	RESIDENTIAL BUSINESS UNKNOWN	The contacts phone type.

InformationComponent

Name	Type	Values	Description
Name	srtring	Varies	The component name of the Name-Value pair
Value	srtring	Varies	The component value of the Name-Value pair.

URL Endpoints

ValidateLead_V3 Inputs

ValidateLead_V3 Outputs

References