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 through 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.

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. If there is no value for `country` the postal code is assumed to be US	`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	`renee.c.paulsen1959@yahoo.com`
`email_hash`	A sha256 or md5 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`

Minimum Inputs

The minimum combination of data points a request must contain in order to have a possibility of returning a 200 response are:

cURL

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, JavaScript, Ruby and Python. If you aren’t comfortable operating in these languages, feel free to use this handy tool to convert from cURL to the language of your choice.

Linkedin URL

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

params = {
    "profile": ["http://linkedin.com/in/seanthorne"],
  	"min_likelihood": 6
}

json_response = client.person.enrichment(**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'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  profile: "http://linkedin.com/in/seanthorne",
  min_likelihood: 6
}

PDLJSClient.person.enrichment(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});

require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

params = {
    "profile": ["http://linkedin.com/in/seanthorne"],
  	"min_likelihood": 6
}

json_response = Peopledatalabs::Enrichment.person(params: params)

if json_response['status'] == 200
    record = json_response['data']
    
    puts \
        "#{record['work_email']}\
        #{record['full_name']}\
        #{record['job_title']}\
        #{record['job_company_name']}"
    
    puts "successfully enriched profile with pdl data"
    
    # Save enrichment data to json file
    File.open("my_pdl_enrichment.jsonl", "w") do |out|
        out.write(JSON.dump(record) + "\n")
    end
else
    puts "Enrichment unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

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)

Email

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

params = {
    "email": ["sean@peopledatalabs.com"] 
}

json_response = client.person.enrichment(**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=sean@peopledatalabs.com'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  email: "sean@peopledatalabs.com"
}

PDLJSClient.person.enrichment(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});

require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

params = {
    "email": ["sean@peopledatalabs.com"] 
}

json_response = Peopledatalabs::Enrichment.person(params: params)

if json_response['status'] == 200
    record = json_response['data']
    
    puts \
        "#{record['work_email']}\
        #{record['full_name']}\
        #{record['job_title']}\
        #{record['job_company_name']}"
    
    puts "successfully enriched profile with pdl data"
    
    # Save enrichment data to json file
    File.open("my_pdl_enrichment.jsonl", "w") do |out|
        out.write(JSON.dump(record) + "\n")
    end
else
    puts "Enrichment unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

import requests, json

API_KEY = # YOUR API KEY

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

params = {
    "api_key": API_KEY,
    "email": ["sean@peopledatalabs.com"]   
}

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)

Email Hash

note you can use md5 or sha256 hashes

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

params = {
    "email_hash": ["e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4"]
}

json_response = client.person.enrichment(**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'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  email_hash: "e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4"
}

PDLJSClient.person.enrichment(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});

require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

params = {
    "email_hash": ["e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4"]
}

json_response = Peopledatalabs::Enrichment.person(params: params)

if json_response['status'] == 200
    record = json_response['data']
    
    puts \
        "#{record['work_email']}\
        #{record['full_name']}\
        #{record['job_title']}\
        #{record['job_company_name']}"
    
    puts "successfully enriched profile with pdl data"
    
    # Save enrichment data to json file
    File.open("my_pdl_enrichment.jsonl", "w") do |out|
        out.write(JSON.dump(record) + "\n")
    end
else
    puts "Enrichment unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

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)

Email and Company

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

params = {
    "company": ["Hallspot", "People Data Labs"],
  	"email": ["sean.thorne@talentiq.co"]
}

json_response = client.person.enrichment(**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=sean.thorne@talentiq.co'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  company: "Hallspot",
  company: "People Data Labs",
  email: "sean.thorne@talentiq.co"
}

PDLJSClient.person.enrichment(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});

require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

params = {
    "company": ["Hallspot", "People Data Labs"],
  	"email": ["sean.thorne@talentiq.co"]
}

json_response = Peopledatalabs::Enrichment.person(params: params)

if json_response['status'] == 200
    record = json_response['data']
    
    puts \
        "#{record['work_email']}\
        #{record['full_name']}\
        #{record['job_title']}\
        #{record['job_company_name']}"
    
    puts "successfully enriched profile with pdl data"
    
    # Save enrichment data to json file
    File.open("my_pdl_enrichment.jsonl", "w") do |out|
        out.write(JSON.dump(record) + "\n")
    end
else
    puts "Enrichment unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

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": ["sean.thorne@talentiq.co"]
}

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)

Name + Company + School

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

params = {
    "company": ["TalentIQ Technologies"],   
  	"first_name": ["Sean"],
    "last_name": ["Thorne"],
    "school": ["University of Oregon"]
}

json_response = client.person.enrichment(**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'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  company: "TalentIQ Technologies",
  first_name: "Sean",
  last_name: "Thorne",
  school: "University of Oregon"
}

PDLJSClient.person.enrichment(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});

require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

params = {
    "company": ["TalentIQ Technologies"],   
  	"first_name": ["Sean"],
    "last_name": ["Thorne"],
    "school": ["University of Oregon"]
}

json_response = Peopledatalabs::Enrichment.person(params: params)

if json_response['status'] == 200
    record = json_response['data']
    
    puts \
        "#{record['work_email']}\
        #{record['full_name']}\
        #{record['job_title']}\
        #{record['job_company_name']}"
    
    puts "successfully enriched profile with pdl data"
    
    # Save enrichment data to json file
    File.open("my_pdl_enrichment.jsonl", "w") do |out|
        out.write(JSON.dump(record) + "\n")
    end
else
    puts "Enrichment unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

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)

Name + Location + Twitter + Phone

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

params = {
    "name": ["Sean Thorne"],   
  	"location": ["SF Bay Area"],
    "profile": ["www.twitter.com/seanthorne5"],
    "phone": ["+15555091234"]
}

json_response = client.person.enrichment(**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'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  name: "Sean Thorne",
  location: "SF Bay Area",
  profile: "www.twitter.com/seanthorne5",
  phone: "+15555091234"
}

PDLJSClient.person.enrichment(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});

require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

params = {
    "name": ["Sean Thorne"],   
  	"location": ["SF Bay Area"],
    "profile": ["www.twitter.com/seanthorne5"],
    "phone": ["+15555091234"]
}

json_response = Peopledatalabs::Enrichment.person(params: params)

if json_response['status'] == 200
    record = json_response['data']
    
    puts \
        "#{record['work_email']}\
        #{record['full_name']}\
        #{record['job_title']}\
        #{record['job_company_name']}"
    
    puts "successfully enriched profile with pdl data"
    
    # Save enrichment data to json file
    File.open("my_pdl_enrichment.jsonl", "w") do |out|
        out.write(JSON.dump(record) + "\n")
    end
else
    puts "Enrichment unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

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)

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 json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

params = {
    "name": ["Sean Thorne"],    
    "profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"]
}

json_response = client.person.enrichment(**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'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  name: "Sean Thorne",
  profile: "www.twitter.com/seanthorne5",
  profile: "linkedin.com/in/seanthorne"
}

PDLJSClient.person.enrichment(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});

require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

params = {
    "name": ["Sean Thorne"],    
    "profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"]
}

json_response = Peopledatalabs::Enrichment.person(params: params)

if json_response['status'] == 200
    record = json_response['data']
    
    puts \
        "#{record['work_email']}\
        #{record['full_name']}\
        #{record['job_title']}\
        #{record['job_company_name']}"
    
    puts "successfully enriched profile with pdl data"
    
    # Save enrichment data to json file
    File.open("my_pdl_enrichment.jsonl", "w") do |out|
        out.write(JSON.dump(record) + "\n")
    end
else
    puts "Enrichment unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

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)

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`	`2`
`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. `"full_name,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

cURL

required=emails

Response must contain a linkedin url

cURL

required=linkedin_url

Response must contain experience and a current professional email

cURL

required=experience AND work_email

Response must contain experience or emails

cURL

required=experience OR emails

Response must contain education and (emails or phone_numbers)

cURL

required=education AND (emails OR phone_numbers)

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

params = {
    "name": ["Sean Thorne"],    
    "profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"],
    "required": "emails"
}

json_response = client.person.enrichment(**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'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  name: "Sean Thorne",
  profile: "www.twitter.com/seanthorne5",
  profile: "linkedin.com/in/seanthorne",
  required: "emails"
}

PDLJSClient.person.enrichment(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});

require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

params = {
    "name": ["Sean Thorne"],    
    "profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"],
    "required": "emails"
}

json_response = Peopledatalabs::Enrichment.person(params: params)

if json_response['status'] == 200
    record = json_response['data']
    
    puts \
        "#{record['work_email']}\
        #{record['full_name']}\
        #{record['job_title']}\
        #{record['job_company_name']}"
    
    puts "successfully enriched profile with pdl data"
    
    # Save enrichment data to json file
    File.open("my_pdl_enrichment.jsonl", "w") do |out|
        out.write(JSON.dump(record) + "\n")
    end
else
    puts "Enrichment unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

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)

Valid Required Parameters

Any top-level fields may be specified in the required params. See example fields in the section below:

Parameter Name
`birth_date`
`education`
`emails`
`experience`
`facebook_id`
`facebook_username`
`full_name`
`sex`
`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`
`personal_emails`
`phone_numbers`
`profiles`
`skills`
`twitter_username`
`work_email`

Full Example Response

JSON

{
  "status": 200,
  "likelihood": 10,
  "data": {
    "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
    "full_name": "sean thorne",
    "first_name": "sean",
    "middle_initial": "f",
    "middle_name": "fong",
    "last_name": "thorne",
    "sex": "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": "sean@peopledatalabs.com",
    "personal_emails": ["sean@gmail.com"],
    "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": "sthorne@uoregon.edu",
        "type": null
      },
      {
        "address": "sean@hallspot.com",
        "type": "professional"
      },
      {
        "address": "sean@talentiq.co",
        "type": "professional"
      },
      {
        "address": "sean.thorne@talentiq.co",
        "type": "professional"
      },
      {
        "address": "sean@peopledatalabs.com",
        "type": "current_professional"
      },
      {
        "address": "sthorne@peopledatalabs.com",
        "type": "current_professional"
      },
      {
        "address": "sean.thorne@peopledatalabs.com",
        "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"
      }
    ]
  }
}

​Person Enrichment API Access and Billing

​Usage

​Requests

​Rate Limiting

​Input Parameters

​Minimum Inputs

​Response

​Likelihood Score

​What is it?

​How to use it (min_likelihood param)

​Examples

​Linkedin URL

​Email

​Email Hash

​Email and Company

​Name + Company + School

​Name + Location + Twitter + Phone

​Multiple Values for the Same Parameter

​Controlling What Counts As A Successful Response

​min_likelihood

​Required Parameter

​Examples

​Valid Required Parameters

​Full Example Response

Person Enrichment API Access and Billing

Usage

Requests

Rate Limiting

Input Parameters

Minimum Inputs

Response

Likelihood Score

What is it?

How to use it (`min_likelihood` param)

Examples

Linkedin URL

Email

Email Hash

Email and Company

Name + Company + School

Name + Location + Twitter + Phone

Multiple Values for the Same Parameter

Controlling What Counts As A Successful Response

min_likelihood

Required Parameter

Examples

Valid Required Parameters

Full Example Response