Person Match

A Person Match request returns match results of people based on criteria of various match inputs. Your partner agreement restricts the available returned match output. The HTTP request for Person Match begins with the URL structure:

http://partnerapi.zoominfo.com/partnerapi/person/match?

Input Parameters – Person Match

The table below shows input parameters that can be used in Person Match queries. Parameter descriptions are grouped as follows:

  • Group - Grouping for match field permissions.
  • Field Name - Name of input parameter.
  • Required - Denotes whether or not the field is required in a match request.
  • Value - Valid values for this input parameter.
  • Notes - Information related to the input parameter.
  • Key - Denotes whether or not the key generation uses the field. The order in which the parameters appear in the table is the order in which you should use them in the key. For match requests, the key for each input record passed into the request must have one set of parameter values. Use each set of parameter values in the key in the same order as their respective input records.


Group
Field Name
Required
Value
Notes
Key
Request-level Default
pc
required

Partner code (or partner name) assigned to you
no
key
required

A string consisting of 5 parameters concatenated together, then encrypted with MD5. Parameters are:
 1) first 2 characters of every match term in each input record
 2) your partner password
 3) today's day (not padded with zero)
 4) today's month (not padded with zero)
 5) today's year (4 digit)
no
numMatches
optional
number from 1 to 10
Limits the match results returned to the given number of match results per input record
no
echoInput
optional
true or false
Default value is false. If you set it to be false, the XML output displays only the unique Id for each input record. Alternatively, the XML output displays the unique Id and all other input parameters for each input record
no
outputFieldOptions
optional

Person Match Query has the following optional output fields:
  • localAddress
  • companyAddress
  • companyRevenue
  • companyRevenueNumeric
  • companyRevenueRange
  • companyEmployeeCount
  • companyEmployeeRange
  • companyTopLevelIndustry
  • companyWebsite
  • jobFunction
  • managementLevel
  • companyLogo
  • companyType
  • hasCanadianEmail
  • nameSuffix
  • companyHashtags
  • orderHashtags
  • gender 
  • techAttributes
To return one or more of these fields, specify the above output field name(s). To return multiple optional output fields, separate the values with a comma. For example, "outputFieldOptions=localAddress,companyAddress" will return localAddress and companyaddress in the XML output,
no
matchCompany
optional
true or false
This parameter does nothing and should no longer be used.  By default, when a Person Match cannot be found, the person match request will always attempt to return a Company Match, if possible.
no
Input Record-level Default
uniqueInputId
optional

Unique string you use to identify a particular match request input record within a match request
no
personId
optional

Unique ZoomInfo identifier of the person to be matched by a particular input record
yes
fullName
optional

Full name of person to be matched by a particular input record. FullName cannot be used with firstName and/or lastName.
yes
firstName
optional

First name of person to be matched by a particular input record. FirstName cannot be used with fullName.
yes
lastName
optional

Last name of person to be matched by a particular input record. LastName cannot be used with fullName.
yes
emailAddress
optional

Email address of the person to be matched by a particular input record
yes
companyId
optional
.
Unique ZoomInfo identifier of the company that the person to be matched by a particular input record works or has worked
yes
companyName
optional

Name of the company for which the person to be matched by a particular input record works or has worked
yes
jobTitle
optional

Current job title of the person to be matched by a particular input record
yes
phone
optional

Phone number for the person to be matched by a particular input record.
yes
state
optional

Searches for people in one or more US states. Accepts multiple values by passing a comma-separated list (also accepts USA-all or Canada-all). Supports State abbreviations(MA,CA). It is case-insensitive. Blank values are allowed.

yes
zipcode
optional

Zip code for the person to be matched by a particular input record.
yes
country
optional

Searches for people in one or more countries. Accepts multiple values by passing a comma-separated lis (Example: USA,Sweden,Brazil) It is case-insensitive. Blank values are allowed.


yes
hashedEmailoptional
Hashed email value for person to be matched by a particular input record. Allows matching via an email address with the extra security of not exposing the email. Currently we support four hash algorithms: MD5, SHA1, SHA256 and SHA512.
no
externalURloptional
Social media URL for the person to be matched by a particular input record. Currently we support only the URL from LinkedIn
no


Example Person Match Request

The following example shows a Person Match query. The input parameters include:

  • true for echoInput
  • jonfor firstName
  • smith for lastName
  • jsmith@leonardinsurance.com for emailAddress
  • leonard for companyName

The Person Match query request can be structured like this:

http://partnerapi.zoominfo.com/partnerapi/person/match?pc=PartnerCode&firstName=jon&lastName=smith&emailAddress=jsmith@leonardinsurance.com&companyName=leonard&echoInput=true&key=EncryptedKey

<personMatchResponse xmlns="http://partnerapi.zoominfo.com/partnerapistatic/
xsd/V1/PersonMatchResponse.xsd">
 <inputParameters>
 <parameter>
 <name>echoInput</name>
 <value>true</value>
 </parameter>
 </inputParameters>
 <matchResults>
 <personMatchResults>
 <personMatchResult>
 <matchPersonInput>
 <uniqueInputId>Zoom-1</uniqueInputId>
 <firstName>jon</firstName>
 <lastName>smith</lastName>
 <emailAddress>jsmith@leonardinsurance.com</emailAddress>
 <companyName>leonard</companyName>
 </matchPersonInput>
 <personMatches>
 <personMatch>
 <matchConfidence>90</matchConfidence>
 <personId>-108503</personId>
 http://www.staging.zoominfo.com/#!search/profile/person?personId=-108503&targetid=profile
 http://api.zoominfo.staging.com/partnerapi/xmloutput.aspx
 ?query_type=person_detail&PersonID=-
 108503&pc=PartnerCode&key=EncryptedKey</personDetailXmlUrl>
 <lastMentioned>3/21/2013</lastMentioned>
 <isUserPosted>True</isUserPosted>
 <isPast>False</isPast>
 <referencesCount>51</referencesCount>
 http://www.aogexpo.com.au/ckfinder/userfiles/images/speakers
 /Jonathan%20Smith%20photo.jpg</imageUrl>
 <firstName>Jon</firstName>
 <lastName>Smith</lastName>
 <email>jsmith@leonardinsurance.com</email>
 <phone>(330) 266-1904</phone>
 <fax>(330) 498-9946</fax>
 <currentEmployment>
 <jobTitle>Vice President</jobTitle>
 <company>
 <companyId>22462584</companyId>
 http://www.staging.zoominfo.com/#!search/profile/company?companyId=22462584&targetid=profile
 http://api.zoominfo.staging.com/partnerapi/xmloutput.aspx
 ?query_type=company_detail&CompanyID=22462584&pc=PartnerCode&
 key=EncryptedKey</companyDetailXmlUrl>
 <companyName>Leonard Insurance Services Agency Inc</companyName>
 <companyPhone>(330) 266-1974</companyPhone>
 <companyWebsite>www.leonardinsurance.com</companyWebsite>
 <companySic4>6411</companySic4>
 </company>
 </currentEmployment>
 <industry>Insurance</industry>
 </personMatch>
 </personMatches>
 </personMatchResult>
 </personMatchResults>
 </matchResults>
</personMatchResponse>



Output Parameters – Person Match

The table below shows output parameters that can be used in Person Match queries. These parameters are grouped in the following categories:

  • Group - The grouping for output field permissions. The permission groups configured for a partner determine the output fields present in a response.
  • Parent Name - Name of the output element
  • Child Name - Name of a child element of a parent element specified in the parent name column
  • Notes - Information related to the output field
Group
Parent Name
Child Name
Notes
Default
PersonID

Unique identifier for the person
ZoomPersonURL

URL for the person's zoominfo.com public profile
PersonDetailXmlUrl

API request URL for Person Detail. Returned output will be in XML format
LastMentioned

Date the person's profile was last updated
IsUserPosted

Designates if the person created the profile manually
IsPast

Designates if the most recent job title for a person is a past position
ReferencesCount

Number of web references the person has
ImageUrl

URL for the person's profile image
FirstName

First name of the person
MiddleInitial

Middle initial of the person
LastName

Last name of the person
LocalAddress

Address of the person's local office
Optional:This output field won't beshown unless the 'outputFieldOptions' parameter contains this output field
Street
Street for the local address.
City
City for the local address
State
State or province for the local address
Zip 

Postal code for the local address
CountryCode
Country for the local address
CurrentEmployment








JobTitle
Where the person is currently employed. CurrentEmployment contains child elements. NOTE: If the person has no current employment, then the CurrentEmployment element will not be present.

Person's title at current place of employment
JobFunction
Person's job function at their current place of employment
Optional:This output field won't beshown unless the 'outputFieldOptions' parameter contains this output field
ManagementLevel
The person's management level at their current place of employment
Optional:This output field won't beshown unless the 'outputFieldOptions' parameter contains this output field
Company

Contains the following child elements with information about the person's current company
CompanyID
Unique identifier used by ZoomInfo for company
ZoomCompanyUrl
URL for the company's zoominfo.com public profile
CompanyDetailXmlUrl
API request URL for Company Detail. Returned output will be in XML format
CompanyName
Name of the company
CompanyPhone
Phone number of the company headquarters.
CompanyAddress

Address for the person's current company headquarters.
Optional:This output field won't beshown unless the 'outputFieldOptions' parameter contains this output field
Street
Street for the company address
City
City for the company address
State
State or province for the company address
Zip
Postal code for the company address
CountryCode
Country for the company address
CompanyRevenue
Annual gross revenue for the company. Optional: it won't be shown unless the 'outputFieldOptions' parameter contains this output
CompanyRevenueIn000s
Numeric annual gross revenue for the company in 1000's. Optional:This ouput field won't be shown unless the 'ouputFieldOptions" parameter contains "companyRevenueNumeric"
CompanyRevenueRange
Revenue range for the company. Optional:This output field won't be shown unless the 'outputFieldOptions' parameter contains “companyRevenueRange”
CompanyEmployeeCount
Employee head count for the company. Optional: It won't be shown unless the 'outputFieldOptions' parameter contains this output field
CompanyEmployeeCountRange
Employee head count range for the company. Optional:This output field won't be shown unless the 'outputFieldOptions' parameter contains “companyEmployeeRange”
CompanyWebsite
The web domain for the company in http://www.example.com format
CompanyLogo
The URL which can be used to retrieve the logo for the company.
CompanySic4
The company Standard Industry Code (SIC). For more information about SIC, please see http://en.wikipedia.org/wiki/Standard_Industrial_Classification
Industries  
TopLevelIndustry

Top Level (and therefore least specific) Industry that the person works in. A person can have multiple top level industries.  Top level industry tags are based on the current employment company. Optional:This output field won't be shown unless the 'outputFieldOptions' parameter contains “companyTopLevelIndustry”
Industry

Industry the person currently works in. A person can have multiple industries. Industry tags are based on the current employment company.
Contact Info
Email

Person's email address in example@example.com format
Phone

Best available phone number for the person
Fax

Fax number for the person's current company


Person Match – Tips

ZoomInfo utilizes Approximate String Matching (also called, fuzzy matching) when comparing names. For example, for Person Match, the input of "Mary Beth" may match Mary Ann, Maryann, Mary Jane, Mary Lynn, or Marianne. Likewise, Anne-Marie may return a match to AnneMarie.

Enhanced Person Match

An Enhanced Person Match request returns match results of people based on criteria of various match inputs. However, an Enhanced Person Match request also returns data analysis output elements consisting of qualityMetrics01, computedTitle, and normalizedValues01. Your partner agreement restricts the available returned match output. The HTTP request for Enhanced Person Match begins with the URL structure:

http://partnerapi.zoominfo.com/partnerapi/v3/enhanced/person/match?

Please see Input Parameters – Person Matchfor the input parameters that can be used in Person Match queries.

Example Enhanced Person Match Request

The following example shows an Enhanced Person Match query. The input parameters include:

The Enhanced Person Match query request can be structured like this:

https://partnerapi.zoominfo.com/partnerapi/v3/enhanced/person/match?pc=PartnerCode&firstName=jon&lastName=smith&emailAddress=jsmith@leonardinsurance.com&companyName=leonard&echoInput=true&key=OAuth-Access-Token

<personMatchResponse
 xmlns="http://partnerapi.zoominfo.com/partnerapistatic/xsd/V1/PersonMatchResponse.xsd">
<inputParameters>
<parameter>
 <name>echoInput</name>
<value>true</value>
 </parameter>
</inputParameters>
<matchResults>
 <personMatchResults>
 <personMatchResult>
<matchPersonInput>
<uniqueInputId>Zoom-1</uniqueInputId>
<firstName>jon</firstName>
<lastName>smith</lastName>
<emailAddress>jsmith@leonardinsurance.com</emailAddress>
<companyName>leonard</companyName>
</matchPersonInput> 
<personMatches>
<personMatch>
<matchConfidence>99.99999998999999</matchConfidence>
<personId>-108503</personId>
<zoomPersonUrl>http://www.zoominfo.com/#!search/profile/person?personId=
-108503&targetid=profile</zoomPersonUrl>
 <lastMentioned>11/13/2015</lastMentioned>
<isUserPosted>False</isUserPosted>
<isPast>False</isPast>
<referencesCount>40</referencesCount>
<firstName>Jon</firstName>
<middleInitial>D.</middleInitial>
<lastName>Smith</lastName>
<email>jonsmith@bigrocktoyota.com.au</email>
<phone>(954)970-2969</phone>
<currentEmployment>
<jobTitle>Business Development and Account Manager</jobTitle>
 <company>
 <companyId>369065759</companyId><zoomCompanyUrl>http://www.zoominfo.com/#!search/profile/company?companyId=369065759&targetid=profile</zoomCompanyUrl>
<companyName>Big Rock Toyota and Automotive Holdings GroupLimited</companyName>
 </company>
</currentEmployment>
<dataAnalysisResults>
<qualityMetrics01>
 <isKnownFirstName>Yes</isKnownFirstName>
 <isKnownLastName>Yes</isKnownLastName>
<isKnownFullName>Yes</isKnownFullName>
 <isMalformedEmail>No</isMalformedEmail>
<isFreeEmail>No</isFreeEmail>
<isGenericEmail>No</isGenericEmail>
 <isEmailMatchesPersonName>Yes</isEmailMatchesPersonName>
 <isEmailMatchesCompanyName>No</isEmailMatchesCompanyName>
<hasMoved>Yes</hasMoved>
</qualityMetrics01>
<normalizedValues01>
<firstName>Jon</firstName>
<lastName>Smith</lastName>
</normalizedValues01>
</dataAnalysisResults>
</personMatch>
</personMatches
 </personMatchResult>
</personMatchResults>
</matchResults>
</personMatchResponse>


Output Parameters – Enhanced Person Match

The table below shows output parameters that can be used in Enhanced Person Match queries. These parameters are grouped in the following categories:

  • Group - The grouping for output field permissions. The permission groups configured for a partner determine the output fields present in a response.
  • Parent Name - Name of the output element
  • Child Name - Name of a child element of a parent element specified in the parent name column
  • Notes - Information related to the output field
Group
Parent Name
Child Name
Notes

(See Output Parameters – Person Match
for additional Output Parameters)


Default
qualityMetrics01
isKnownFirstName
Validation indicating ZoomInfo recognizes first name input value as a known first name using multiple sources including the U.S. Census

isKnownLastName
Validation indicating ZoomInfo recognizes last name input value as a known last name using multiple sources including the U.S. Census

isKnownFullName
Validation indicating ZoomInfo recognizes full name input value as a known full name using multiple sources including the U.S. Census

isMalformedEmail
Validation indicating ZoomInfo recognizes email address input value is malformed and does not follow the xyz@domain syntax

isFreeEmail
Validation indicating ZoomInfo recognizes email address input value as a free or temporary email. Example: john.smith@hotmail.com returns a value of yes

isGenericEmail
 Validation indicating ZoomInfo recognizes email input value as a role based username. Example: sales@zoominfo.com would return a value of yes

isEmailMatchesPersonName
Validation indicating ZoomInfo recognizes email address input value uses a pattern that matches the persons name. Example: full name=John Smith email=john.smith@zoominfo.com would return a value of yes

isEmailMatchesCompanyName
Validation indicating ZoomInfo recognizes a match between the email domain input value and known domains for the company.

isPhoneAreaMatchesCompanyCountry
Validation indicating ZoomInfo recognizes a match between the phone input value and the known country location for the company

isPhoneAreaMatchesCompanyState
Validation indicating ZoomInfo recognizes a match between the phone input value and the known state location for the company

isPhoneNumberMatchesPersonalNumber
Validation indicating ZoomInfo recognizes a match between the phone input value and the known phone numbers we have for the person

isPhoneNumberMatchesCompanyNumber
Validation indicating ZoomInfo recognizes a match between the phone input value and the known phone number we have for the company headquarters

isPhoneNumberMatchesCompanyExtension
Validation indicating ZoomInfo recognizes a match between the phone input value and the known phone extensions we have for the company

hasMoved
Validation indicating ZoomInfo recognizes the person company input value does not match ZoomInfo current company but does match known employment history.
computedTitle
jobFunction
ZoomInfo computed job function based on job title input value

jobHierarchy
ZoomInfo computed job hierarchy based on job title input value
normalizedValues01
prefix
ZoomInfo normalized name prefix based on input value

firstName
ZoomInfo normalized first name based on input value


middleInitial
ZoomInfo normalized middle initial based on input value

lastName
ZoomInfo normalized last name based on input value

suffix
ZoomInfo normalized name suffix based on input value

title
ZoomInfo normalized job title based on input value

phone
ZoomInfo normalized phone number based on input value

state
ZoomInfo normalized person state based on input value

country
ZoomInfo normalized person country based on input value

zip
ZoomInfo normalized person zip code based on input value

Was this article helpful?

Can’t find what you’re looking for?

Contact our award-winning customer care team.