The PeopleDataLabs Developer Hub

Welcome to the PeopleDataLabs developer hub. You'll find comprehensive guides and documentation to help you start working with PeopleDataLabs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Changelog

Enrichment API

The endpoint for the enrichment api is /v5/person/enrich

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.

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 NameDescriptionExample
nameThe person's full name, at least first and lastJennifer C. Jackson
first_nameThe person's first nameJennifer
last_nameThe person's last nameJackson
middle_nameThe person's middle nameCassandra
locationThe location in which a person lives. Can be anything from a street address to a country nameMedford, OR USA
street_addressA street address in which the person lives1234 Main Street
localityA locality in which the person livesBoise
regionA state or region in which the person livesIdaho
countryA country in which the person livesUnited States
postal_codeThe postal code in which the person lives, must be used with either a country or a region83701
companyA name, website, or social url of a company where the person has workedAmazon Web Services
schoolA name, website, or social url of a university or college the person has attendeduniversity of iowa
phoneA phone number the person has used in any format.+1 555-234-1234
emailAn email the person has used[email protected]
email_hashA sha256 email hashe206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4
profileA social profile the person has used List of available social profiles.https://linkedin.com/in/seanthorne
lidA LinkedIn numerical ID145991517
birth_dateThe person's birth date. Either the year, or a full birth date1996-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)
    )

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.

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.

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.

Examples

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()

###
GET /v5/person/enrich?api_key=xxxx&company=People Data Labs&company=Hallspot&[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()

###
GET /v5/person/enrich?api_key=xxxx&min_likelihood=6&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

Every parameter can take multiple values. To do so, simply append the parameter with values as many times as needed.

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     DescriptionDefault
min_likelihoodThe minimum likelihood score a response must have to return a 2000
requiredParameter 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              DescriptionDefault
titlecaseAll 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_includeA 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_matchedIf 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']

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.

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

Updated about 12 hours ago


Enrichment API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.