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 a JSON object to capture input parameters 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.

Minimum Inputs

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 1 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

What is it?

Every match that the API finds during the enrichment process is assigned a likelihood score, which is an integer between 1 - 10 representing the confidence that the returned profile is the same as the profile requested. A score of 1 represents a very low confidence level, and 10 represents the highest degree of confidence. The likelihood score is logarithmic such that 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.

As an 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 (since there might be a lot of John Smiths in New York). 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 correctly returning the intended John Smith.

How to use it (min_likelihood param)

You can use the min_likelihood parameter in your API request to specify a threshold likelihood score you want the response to meet or exceed. This parameter allows you to specify the tradeoff between precision and recall. In other words, using a high min_likelihood value will only return very strong matches, but at the risk of not returning any match at all if none can be found above the min_likelihood threshold. Alternatively, using a low min_likelihood value is more likely to give you a match, but at the cost of returning a potentially weaker match.

Some general rules of thumb for setting this parameter are as follows:

• For use cases which rely on a high degree of data accuracy, use a value of ≥ 6 for the min_likelihood value
• Requests made with only a few less-specific data points, e.g. a name and location, generally return a response with a likelihood score ≤ 4
• Requests made with just an email or non-mobile phone generally return a score between 3 and 6
• Requests with a mobile phone or LinkedIn return a likelihood score ≥ 7

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.

Linkedin URL

import requests, json

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

if json_response["status"] == 200:
  record = json_response['data']

  print(
    record['work_email'],
    record['full_name'],
    record['job_title'],
    record['job_company_name']
  )

  print(f"successfully enriched profile with pdl data")

  # Save enrichment data to json file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

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'

Email

import requests, json

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

if json_response["status"] == 200:
  record = json_response['data']

  print(
    record['work_email'],
    record['full_name'],
    record['job_title'],
    record['job_company_name']
  )

  print(f"successfully enriched profile with pdl data")

  # Save enrichment data to json file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

curl -X GET -G \
  'https://api.peopledatalabs.com/v5/person/enrich' \
  -H 'X-Api-Key: xxxx' \
  --data-urlencode '[email protected]'

Email Hash

note you can use md5 or sha256 hashes

import requests, json

API_KEY = # YOUR API KEY

pdl_url = "https://api.peopledatalabs.com/v5/person/enrich"

params = {
    "api_key": API_KEY,
    "email_hash": ["e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4"]   
}

json_response = requests.get(pdl_url,  params=params).json()

if json_response["status"] == 200:
  record = json_response['data']

  print(
    record['work_email'],
    record['full_name'],
    record['job_title'],
    record['job_company_name']
  )

  print(f"successfully enriched profile with pdl data")

  # Save enrichment data to json file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

curl -X GET -G \
  'https://api.peopledatalabs.com/v5/person/enrich' \
  -H 'X-Api-Key: xxxx' \
  --data-urlencode 'email_hash=e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4'

Email and Company

import requests, json

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

if json_response["status"] == 200:
  record = json_response['data']

  print(
    record['work_email'],
    record['full_name'],
    record['job_title'],
    record['job_company_name']
  )

  print(f"successfully enriched profile with pdl data")

  # Save enrichment data to json file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

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]'

Name + Company + School

import requests, json

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

if json_response["status"] == 200:
  record = json_response['data']

  print(
    record['work_email'],
    record['full_name'],
    record['job_title'],
    record['job_company_name']
  )

  print(f"successfully enriched profile with pdl data")

  # Save enrichment data to json file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

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'

Name + Location + Twitter + Phone

import requests, json

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

if json_response["status"] == 200:
  record = json_response['data']

  print(
    record['work_email'],
    record['full_name'],
    record['job_title'],
    record['job_company_name']
  )

  print(f"successfully enriched profile with pdl data")

  # Save enrichment data to json file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

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, json

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

if json_response["status"] == 200:
  record = json_response['data']

  print(
    record['work_email'],
    record['full_name'],
    record['job_title'],
    record['job_company_name']
  )

  print(f"successfully enriched profile with pdl data")

  # Save enrichment data to json file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

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']

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, json

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

if json_response["status"] == 200:
  record = json_response['data']

  print(
    record['work_email'],
    record['full_name'],
    record['job_title'],
    record['job_company_name']
  )

  print(f"successfully enriched profile with pdl data")

  # Save enrichment data to json file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

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 example fields in the section below:

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]",
    "personal_emails": ["[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"
      }
    ],
  }
}```