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.

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.

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.

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: