The endpoint for the person enrichment api is https://api.peopledatalabs.com/v5/person/enrich
Person Enrichment API Access and Billing
You can access the Enrichment API via our self-signup dashboard
When a matching person is returned, the HTTP Response code will be 200
, and when no matching person is found or returned, the HTTP Response code will be a 404
. We charge per match.
Usage
The person enrichment API provides a one to one match, providing up to date information on a unique individual.
Requests
See Authentication and Requests to see possible ways to input requests. We recommend using the body of your request and will do so in the examples below.
Rate Limiting
Our default limit for free customers is 100/min. Our default limit for paying customers is 1000/min.
In order to allow for more enrichments without putting too much strain on our system, you can use the v5/bulk endpoint to increase the number of enrichments per request, artificially increasing your rate limit up to 100x.
Input Parameters
Data points on the queried person are added as key/value pairs to the query string of a v5
request.
The following parameters can be used to specify information on the requested person. Adding more data points to a request increases the probability of a 200
response, and further, will increase the accuracy of the response's Likelihood Score.
All query parameters listed below are optional.
Parameter Name | Description | Example |
---|---|---|
name | The person's full name, at least first and last | Jennifer C. Jackson |
first_name | The person's first name | Jennifer |
last_name | The person's last name | Jackson |
middle_name | The person's middle name | Cassandra |
location | The location in which a person lives. Can be anything from a street address to a country name | Medford, OR USA |
street_address | A street address in which the person lives | 1234 Main Street |
locality | A locality in which the person lives | Boise |
region | A state or region in which the person lives | Idaho |
country | A country in which the person lives | United States |
postal_code | The postal code in which the person lives, must be used with either a country or a region | 83701 |
company | A name, website, or social url of a company where the person has worked | Amazon Web Services |
school | A name, website, or social url of a university or college the person has attended | university of iowa |
phone | A phone number the person has used in any format. | +1 555-234-1234 |
email | An email the person has used | [email protected] |
email_hash | A sha256 email hash | e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4 |
profile | A social profile the person has used List of available social profiles. | https://linkedin.com/in/seanthorne |
lid | A LinkedIn numerical ID | 145991517 |
birth_date | The person's birth date. Either the year, or a full birth date | 1996-10-01 |
The minimum combination of data points a request must contain in order to have a possibility of returning a 200
response are:
profile OR email OR phone OR email_hash OR lid OR (
(
(first_name AND last_name) OR name) AND
(locality OR region OR company OR school OR location OR postal_code)
)
Response
When an API request is executed, the queried data points are preprocessed and built into a query, which is then executed against our api dataset. If the query yields 1 or more matching persons from the dataset, the person returned in the API response is the one who is most likely to be the same person as the person requested and it will return a 200
HTTP response code. If we do not find a match we will return a 404
HTTP response code.
Abridged Response Example (full example here):
{
"status": 200,
"likelihood": 10,
"data": {
"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
"full_name": "sean thorne",
...
}
}
This degree of confidence is represented by the likelihood
field in the API response. The likelihood
field is an integer between 0
and 10
that represents how confident we are the person returned is the same as the person requested. You can read more details here. The minimum likelihood score a response must possess in order to return a 200
can be controlled in the api request using the min_likelihood
param, described in the parameters section below.
Likelihood Score
The likelihood score gives you the ability to control match precision vs. recall in the API. A higher likelihood
score indicates that the data that a match is higher confidence. For example, requesting for "John Smith" in "New York" does not provide enough information to yield a result that we can confidently say is the exact John Smith that was requested. However if an email
, a phone
, and a street_address
were all attached and matched in our data, we can be highly confident we are returning the same John Smith.
Examples
When using a URL, all query parameters should be separated by an ampersand &
. When using code, all request parameters should be lists.
All examples are provided in cURL and Python. If you aren't comfortable operating in either of these languages, feel free to use this handy tool to convert from cURL to the language of your choice.
import requests
API_KEY = # YOUR API KEY
pdl_url = "https://api.peopledatalabs.com/v5/person/enrich"
params = {
"api_key": API_KEY,
"company": ["Hallspot", "People Data Labs"],
"email": ["[email protected]"]
}
json_response = requests.get(pdl_url, params=params).json()
###
curl -X GET -G \
'https://api.peopledatalabs.com/v5/person/enrich'\
-H 'X-Api-Key: xxxx' \
--data-urlencode 'company=People Data Labs'\
--data-urlencode 'company=Hallspot'\
--data-urlencode '[email protected]'
import requests
API_KEY = # YOUR API KEY
pdl_url = "https://api.peopledatalabs.com/v5/person/enrich"
params = {
"api_key": API_KEY,
"profile": ["http://linkedin.com/in/seanthorne"],
"min_likelihood": 6
}
json_response = requests.get(pdl_url, params=params).json()
###
curl -X GET -G \
'https://api.peopledatalabs.com/v5/person/enrich'\
-H 'X-Api-Key: xxxx' \
--data-urlencode 'min_likelihood=6'\
--data-urlencode 'profile=http://linkedin.com/in/seanthorne'
import requests
API_KEY = # YOUR API KEY
pdl_url = "https://api.peopledatalabs.com/v5/person/enrich"
params = {
"api_key": API_KEY,
"email": ["[email protected]"]
}
json_response = requests.get(pdl_url, params=params).json()
curl -X GET -G \
'https://api.peopledatalabs.com/v5/person/enrich' \
-H 'X-Api-Key: xxxx' \
--data-urlencode '[email protected]'
import requests
API_KEY = # YOUR API KEY
pdl_url = "https://api.peopledatalabs.com/v5/person/enrich"
params = {
"api_key": API_KEY,
"company": ["TalentIQ Technologies"],
"first_name": ["Sean"],
"last_name": ["Thorne"],
"school": ["University of Oregon"]
}
json_response = requests.get(pdl_url, params=params).json()
curl -X GET -G \
'https://api.peopledatalabs.com/v5/person/enrich' \
-H 'X-Api-Key: xxxx' \
--data-urlencode 'company=TalentIQ Technologies' \
--data-urlencode 'first_name=Sean' \
--data-urlencode 'last_name=Thorne' \
--data-urlencode 'school=University of Oregon'
import requests
API_KEY = # YOUR API KEY
pdl_url = "https://api.peopledatalabs.com/v5/person/enrich"
params = {
"api_key": API_KEY,
"name": ["Sean Thorne"],
"location": ["SF Bay Area"],
"profile": ["www.twitter.com/seanthorne5"],
"phone": ["+15555091234"]
}
json_response = requests.get(pdl_url, params=params).json()
curl -X GET -G \
'https://api.peopledatalabs.com/v5/person/enrich' \
-H 'X-Api-Key: xxxx' \
--data-urlencode 'name=Sean Thorne' \
--data-urlencode 'location=SF Bay Area' \
--data-urlencode 'profile=www.twitter.com/seanthorne5' \
--data-urlencode 'phone=+15555091234'
Multiple Values for the Same Parameter
Most parameters can take multiple values. To do so, simply append the parameter with values as many times as needed. The only parameters that cannot exist multiple times are the locality
, region
, country
, and street_address
parameters, since these are all linearly related and multiple inputs would make it impossible to match. To match on multiple locations use the location
parameter.
import requests
API_KEY = # YOUR API KEY
pdl_url = "https://api.peopledatalabs.com/v5/person/enrich"
params = {
"api_key": API_KEY,
"name": ["Sean Thorne"],
"profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"]
}
json_response = requests.get(pdl_url, params=params).json()
curl -X GET -G \
'https://api.peopledatalabs.com/v5/person/enrich' \
-H 'X-Api-Key: xxxx' \
--data-urlencode 'name=Sean Thorne' \
--data-urlencode 'profile=www.twitter.com/seanthorne5' \
--data-urlencode 'profile=linkedin.com/in/seanthorne'
Controlling What Counts As A Successful Response**
These parameters can be used to describe the characteristics an API response must possess to return a 200
.
Parameter Name | Description | Default |
---|---|---|
min_likelihood | The minimum likelihood score a response must have to return a 200 | 0 |
required | Parameter specifying the fields and data points a response must have to return a 200 |
For more information on the min_likelihood
param, see the likelihood section, and for more information on the required
param, see the required param section.
Controlling What the Response Looks Like
The following parameter can be used to control/specify certain things about the formatting of the person data in the API response.
Parameter Name | Description | Default |
---|---|---|
titlecase | All text in the data of API responses is returned as lowercase by default. Setting titlecase to true will titlecase the person data in 200 responses. | false |
data_include | A comma-separated string of fields that you would like the response to include. eg. "names.clean,emails.address" . Begin the string with a - if you would instead like to exclude the specified fields. If you would like to exclude all data from being returned, use data_include="" . | |
include_if_matched | If set to true , includes a top-level (alongside "data" , "status" , etc) field "matched" which includes a value for each queried field parameter that was "matched-on" during our internal query. | false |
More on the include_if_matched field
Check out the match object request for the following example queries:
name=sean thornelius&profile=linkedin.com/in/seanthorne
'matched': ['linkedin']
first_name=sean&last_name=thorne&company=people data labs&location=abu dhabi
'matched': ['company', 'name']
min_likelihood
Setting a different min_likelihood
value in the requests allows you to control the specificity of our matches. For use cases which rely on a high degree of data accuracy, only records with a likelihood of approximately 6
or above should be used. By default, match recall is kept very high, so a response which returns a likelihood score of 2
will roughly have just a 10 to 30 percent chance of being the same person as the one requested. Adding more data points to your requests will increase the probability of a 200
response returning a higher likelihood score.
Requests made with only a few data points, e.g. a name and location, will rarely return a 200
response with a likelihood score > 4, and requests made with just an email will rarely return a 200
response with a likelihood score > 6.
Required Parameter
The required parameter ensures that you only get charged for responses which have the data fields you're interested in. You can use any top fields for required parameters except those you use as search parameters/input fields. If you include a field in both the request and the required parameters, the required parameter will not work. The value is formatted as a boolean statements.
Examples
Response must contain an email
required=emails
Response must contain a linkedin url
required=linkedin_url
Response must contain experience and a current professional email
required=experience AND work_email
Response must contain experience or emails
required=experience OR emails
Response must contain education and (emails or phone_numbers)
required=education AND (emails OR phone_numbers)
import requests
API_KEY = # YOUR API KEY
pdl_url = "https://api.peopledatalabs.com/v5/person/enrich"
params = {
"api_key": API_KEY,
"name": ["Sean Thorne"],
"profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"],
"required": "emails"
}
json_response = requests.get(pdl_url, params=params).json()
curl -X GET -G \
'https://api.peopledatalabs.com/v5/person/enrich' \
-H 'X-Api-Key: xxxx' \
--data-urlencode 'name=Sean Thorne' \
--data-urlencode 'profile=www.twitter.com/seanthorne5' \
--data-urlencode 'required=emails'
Valid Required Parameters
Any top-level fields may be specified in the required params. See relevant fields in the section below:
Parameter Name |
---|
birth_date |
education |
emails |
experience |
facebook_id |
facebook_username |
full_name |
gender |
github_username |
industry |
interests |
job_company_name |
job_title |
last_name |
linkedin_id |
linkedin_username |
location_country |
location_locality |
location_name |
location_postal_code |
location_region |
location_street_address |
mobile_phone |
phone_numbers |
profiles |
skills |
twitter_username |
work_email |
Full Example Response
{
"status": 200,
"likelihood": 10,
"data": {
"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
"full_name": "sean thorne",
"first_name": "sean",
"middle_initial": "f",
"middle_name": "fong",
"last_name": "thorne",
"gender": "male",
"birth_year": "1990",
"birth_date": null,
"linkedin_url": "linkedin.com/in/seanthorne",
"linkedin_username": "seanthorne",
"linkedin_id": "145991517",
"facebook_url": "facebook.com/deseanthorne",
"facebook_username": "deseanthorne",
"facebook_id": "1089351304",
"twitter_url": "twitter.com/seanthorne5",
"twitter_username": "seanthorne5",
"github_url": null,
"github_username": null,
"work_email": "[email protected]",
"mobile_phone": "+14155688413",
"industry": "computer software",
"job_title": "co-founder and chief executive officer",
"job_title_role": null,
"job_title_sub_role": null,
"job_title_levels": [
"owner",
"cxo"
],
"job_company_id": "peopledatalabs",
"job_company_name": "people data labs",
"job_company_website": "peopledatalabs.com",
"job_company_size": "11-50",
"job_company_founded": "2015",
"job_company_industry": "computer software",
"job_company_linkedin_url": "linkedin.com/company/peopledatalabs",
"job_company_linkedin_id": "18170482",
"job_company_facebook_url": "facebook.com/peopledatalabs",
"job_company_twitter_url": "twitter.com/peopledatalabs",
"job_company_location_name": "san francisco, california, united states",
"job_company_location_locality": "san francisco",
"job_company_location_metro": "san francisco, california",
"job_company_location_region": "california",
"job_company_location_geo": "37.77,-122.41",
"job_company_location_street_address": "455 market street",
"job_company_location_address_line_2": "suite 1670",
"job_company_location_postal_code": "94105",
"job_company_location_country": "united states",
"job_company_location_continent": "north america",
"job_last_updated": "2020-12-01",
"job_start_date": "2015-03",
"location_name": "san francisco, california, united states",
"location_locality": "san francisco",
"location_metro": "san francisco, california",
"location_region": "california",
"location_country": "united states",
"location_continent": "north america",
"location_street_address": null,
"location_address_line_2": null,
"location_postal_code": null,
"location_geo": "37.77,-122.41",
"location_last_updated": "2020-12-01",
"phone_numbers": [
"+14155688413"
],
"emails": [
{
"address": "[email protected]",
"type": null
},
{
"address": "[email protected]",
"type": "professional"
},
{
"address": "[email protected]",
"type": "professional"
},
{
"address": "[email protected]",
"type": "professional"
},
{
"address": "[email protected]",
"type": "current_professional"
},
{
"address": "[email protected]",
"type": "current_professional"
},
{
"address": "[email protected]",
"type": "current_professional"
}
],
"interests": [
"location based services",
"mobile",
"social media",
"colleges",
"university students",
"consumer internet",
"college campuses"
],
"skills": [
"entrepreneurship",
"start ups",
"management",
"public speaking",
"strategic partnerships",
"strategy",
"fundraising",
"saas",
"enterprise technology sales",
"social networking"
],
"location_names": [
"san francisco, california, united states",
"albany, california, united states",
"portland, oregon, united states"
],
"regions": [
"california, united states",
"oregon, united states"
],
"countries": [
"united states"
],
"street_addresses": [],
"experience": [
{
"company": {
"name": "hallspot",
"size": "1-10",
"id": "hallspot",
"founded": "2013",
"industry": "computer software",
"location": {
"name": "portland, oregon, united states",
"locality": "portland",
"region": "oregon",
"metro": "portland, oregon",
"country": "united states",
"continent": "north america",
"street_address": "1231 northwest hoyt street",
"address_line_2": "suite 202",
"postal_code": "97209",
"geo": "45.52,-122.67"
},
"linkedin_url": "linkedin.com/company/hallspot",
"linkedin_id": "3019184",
"facebook_url": null,
"twitter_url": "twitter.com/hallspot",
"website": "hallspot.com"
},
"location_names": [],
"end_date": "2015-02",
"start_date": "2012-08",
"title": {
"name": "co-founder",
"role": null,
"sub_role": null,
"levels": [
"owner"
]
},
"is_primary": false
},
{
"company": {
"name": "people data labs",
"size": "11-50",
"id": "peopledatalabs",
"founded": "2015",
"industry": "computer software",
"location": {
"name": "san francisco, california, united states",
"locality": "san francisco",
"region": "california",
"metro": "san francisco, california",
"country": "united states",
"continent": "north america",
"street_address": "455 market street",
"address_line_2": "suite 1670",
"postal_code": "94105",
"geo": "37.77,-122.41"
},
"linkedin_url": "linkedin.com/company/peopledatalabs",
"linkedin_id": "18170482",
"facebook_url": "facebook.com/peopledatalabs",
"twitter_url": "twitter.com/peopledatalabs",
"website": "peopledatalabs.com"
},
"location_names": [],
"end_date": null,
"start_date": "2015-03",
"title": {
"name": "co-founder and chief executive officer",
"role": null,
"sub_role": null,
"levels": [
"owner",
"cxo"
]
},
"is_primary": true
}
],
"education": [
{
"school": {
"name": "university of oregon",
"type": "post-secondary institution",
"id": "64LkgfdwWYkCC2TjbldMDQ_0",
"location": {
"name": "eugene, oregon, united states",
"locality": "eugene",
"region": "oregon",
"country": "united states",
"continent": "north america"
},
"linkedin_url": "linkedin.com/school/university-of-oregon",
"facebook_url": "facebook.com/universityoforegon",
"twitter_url": "twitter.com/uoregon",
"linkedin_id": "19207",
"website": "uoregon.edu",
"domain": "uoregon.edu"
},
"end_date": "2014",
"start_date": "2010",
"gpa": null,
"degrees": [],
"majors": [
"entrepreneurship"
],
"minors": []
}
],
"profiles": [
{
"network": "linkedin",
"id": "145991517",
"url": "linkedin.com/in/seanthorne",
"username": "seanthorne"
},
{
"network": "facebook",
"id": "1089351304",
"url": "facebook.com/deseanthorne",
"username": "deseanthorne"
},
{
"network": "twitter",
"id": null,
"url": "twitter.com/seanthorne5",
"username": "seanthorne5"
},
{
"network": "linkedin",
"id": null,
"url": "linkedin.com/in/sean-thorne-9b9a8540",
"username": "sean-thorne-9b9a8540"
},
{
"network": "angellist",
"id": null,
"url": "angel.co/deseanthorne",
"username": "deseanthorne"
},
{
"network": "gravatar",
"id": null,
"url": "gravatar.com/seanthorne5",
"username": "seanthorne5"
},
{
"network": "klout",
"id": null,
"url": "klout.com/seanthorne5",
"username": "seanthorne5"
},
{
"network": "aboutme",
"id": null,
"url": "about.me/sean_thorne",
"username": "sean_thorne"
}
],
"version_status": {
"status": "updated",
"contains": [],
"previous_version": "12.0",
"current_version": "13.0"
}
},
"dataset_version": "13.0"
}```
Updated 9 days ago