The request must have enough data points to find a clear match. A valid request must include at least one of the following groups of optional parameters:
profile OR email OR phone OR email_hash OR lid OR pdl_id OR (
(
(first_name AND last_name) OR name) AND
(company OR school OR location OR street_address OR locality
OR region OR country OR postal_code OR birth_date)
)
api_key
Type
Description
Default
Example
String
Your secret API key.
Your API Key must be included in either the request header or the api_key parameter. For more information about request authentication, see the Authentication page.
The person's birth date: either the year or a full birth date in the format YYYY-MM-DD.
1996-10-01
data_include
Type
Description
Default
Example
String
A comma-separated string of fields that you want the response to include.
"full_name,emails.address"
If this input parameter is not included, the full person profile will be returned.
Include multiple fields by separating each with a comma. Include specific subfields by using dot notation (ex: emails.address).
Exclude field(s) by using - as the first character. Entering - will exclude all of the comma-separated fields following the character and needs to be entered only once. For example, "-education,mobile_phone" will remove the education and mobile_phone fields from the enriched profile response.
To exclude all data from being returned, use data_include="".
pretty
Type
Description
Default
Example
Boolean
Whether the output should have human-readable indentation.
false
true
min_likelihood
Type
Description
Default
Example
Integer
The minimum likelihood score that a response must have in order to count as a match.
2
6
This parameter allows you to balance 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.
By default, match recall is kept very high, so a response that returns a likelihood score of 2 will have roughly a 10-30% chance of being the person requested. Adding more data points to your requests will increase the probability of a successful match (high likelihood score and is actually the requested person).
Some general rules of thumb for setting this parameter:
For use cases which rely on a high degree of data accuracy, use a value of ≥ 6.
Requests made with only a few less-specific data points will return lower scores.
Requests made with only a few data points (for example, a name and a location), will rarely return a likelihood score > 4.
Requests made with just a name return a score between 2 and 5, based on the quality of the match.
Requests made with just an email will rarely return a likelihood score > 6.
include_if_matched
Type
Description
Default
Example
Boolean
If true, the response will include the top-level field matched that contains a list of every query input that matched this profile.
false
true
As an example, if we wanted to enrich Sean Thorne using the following query:
Since Sean's location is in California and not Abu Dhabi in the dataset, the response would contain:
{
"matched": [
"company",
"name"
]
}
required
Type
Description
Default
Example
String
The fields a response must have in order to count as a match.
education AND (emails OR phone_numbers)
This parameter ensures that we only charge you for responses that include the data fields that you're interested in. You can use any top-level fields as required parameters, except those that you use as search parameters, input fields, and fields that are not included in API responses based on your API key. If you include a field in both the request and the required parameter, the required parameter will not work.
Format the value as a boolean statement.
Examples
The response must contain a Linkedin URL:
required=linkedin_url
The response must contain experience and a current work email:
required=experience AND work_email
The response must contain experience or emails:
required=experience OR emails
The response must contain education and either emails or phone_numbers:
required=education AND (emails OR phone_numbers)
import json
# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY
# Create a client, specifying your API key
CLIENT = PDLPY(
api_key="YOUR API KEY",
)
# Create a parameters JSON object
PARAMS = {
"name": ["Sean Thorne"],
"profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"],
"required": "emails"
}
# Pass the parameters object to the Person Enrichment API
json_response = CLIENT.person.enrichment(**PARAMS).json()
# Check for successful response
if json_response["status"] == 200:
record = json_response['data']
# Print selected fields
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)
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';
import fs from 'fs';
// Create a client, specifying your API key
const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });
// Create a parameters JSON object
const params = {
name: "Sean Thorne",
profile: "www.twitter.com/seanthorne5",
profile: "linkedin.com/in/seanthorne",
required: "emails"
}
// Pass the parameters object to the Person Enrichment API
PDLJSClient.person.enrichment(params).then((data) => {
var record = data.data
// Print selected fields
console.log(
record["work_email"],
record["full_name"],
record["job_title"],
record["job_company_name"],
)
console.log("Successfully enriched profile with PDL data.")
// Save enrichment data to JSON file
fs.writeFile("my_pdl_enrichment.jsonl", Buffer.from(JSON.stringify(record)), (err) => {
if (err) throw err;
});
}).catch((error) => {
console.log(error);
});
require 'json'
# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'
# Set your API key
Peopledatalabs.api_key = 'YOUR API KEY'
# Create a parameters JSON object
PARAMS = {
"name": ["Sean Thorne"],
"profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"],
"required": "emails"
}
# Pass the parameters object to the Person Enrichment API
json_response = Peopledatalabs::Enrichment.person(params: PARAMS)
# Check for successful response
if json_response['status'] == 200
record = json_response['data']
# Print selected fields
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
package main
import (
"fmt"
"os"
"encoding/json"
"context"
)
// See https://github.com/peopledatalabs/peopledatalabs-go
import (
pdl "github.com/peopledatalabs/peopledatalabs-go"
pdlmodel "github.com/peopledatalabs/peopledatalabs-go/model"
)
func main() {
// Set your API key
apiKey := "YOUR API KEY"
// Set API key as environmental variable
// apiKey := os.Getenv("API_KEY")
// Create a client, specifying your API key
client := pdl.New(apiKey)
// Create a parameters JSON object
params := pdlmodel.EnrichPersonParams {
PersonParams: pdlmodel.PersonParams {
Name: []string{"Sean Thorne"},
Profile: []string{"www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"},
},
AdditionalParams: pdlmodel.AdditionalParams {
Required: "emails",
},
}
// Pass the parameters object to the Person Enrichment API
response, err := client.Person.Enrich(context.Background(), params)
// Check for successful response
if err == nil {
// Convert the API response to JSON
jsonResponse, jsonErr := json.Marshal(response.Data)
if jsonErr == nil {
var record map[string]interface{}
json.Unmarshal(jsonResponse, &record)
// Print selected fields
fmt.Println(
record["work_email"],
record["full_name"],
record["job_title"],
record["job_company_name"])
fmt.Println("Successfully enriched profile with PDL data.")
// Save enrichment data to JSON file
out, outErr := os.Create("my_pdl_enrichment.jsonl")
defer out.Close()
if outErr == nil {
out.WriteString(string(jsonResponse) + "\n")
}
out.Sync()
}
} else {
fmt.Println("Enrichment unsuccessful. See error and try again.")
fmt.Println("error:", err)
}
}
import requests, json
# Set your API key
API_KEY = "YOUR API KEY"
# Set the Person Enrichment API URL
PDL_URL = "https://api.peopledatalabs.com/v5/person/enrich"
# Create a parameters JSON object
PARAMS = {
"api_key": API_KEY,
"name": ["Sean Thorne"],
"profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"],
"required": "emails"
}
# Pass the parameters object to the Person Enrichment API
json_response = requests.get(PDL_URL, params=PARAMS).json()
# Check for successful response
if json_response["status"] == 200:
record = json_response['data']
# Print selected fields
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
You may specify any top-level fields in the required parameter such as the fields below:
⚠️
You must have access to the appropriate Person Data Field Bundle for any field you provide as a required parameter.
Field Name
birth_date
birth_year
certifications
countries
dataset_version
education
emails
experience
facebook_friends
facebook_id
facebook_url
facebook_username
first_name
first_seen
full_name
sex
github_url
github_username
headline
id
industry
inferred_salary
inferred_years_experience
interests
job_company_12mo_employee_growth_rate
job_company_employee_count
job_company_facebook_url
job_company_founded
job_company_id
job_company_industry
job_company_inferred_revenue
job_company_linkedin_id
job_company_linkedin_url
job_company_location_address_line_2
job_company_location_continent
job_company_location_country
job_company_location_geo
job_company_location_locality
job_company_location_metro
job_company_location_name
job_company_location_postal_code
job_company_location_region
job_company_location_street_address
job_company_name
job_company_size
job_company_ticker
job_company_total_funding_raised
job_company_twitter_url
job_company_type
job_company_website
job_history
job_last_changed
job_last_verified
job_onet_broad_occupation
job_onet_code
job_onet_major_group
job_onet_minor_group
job_onet_specific_occupation
job_onet_specific_occupation_detail
job_start_date
job_summary
job_title
job_title_levels
job_title_role
job_title_sub_role
job_title_class
languages
last_initial
last_name
linkedin_connections
linkedin_id
linkedin_url
linkedin_username
location_address_line_2
location_continent
location_country
location_geo
location_last_updated
location_locality
location_metro
location_name
location_names
location_postal_code
location_region
location_street_address
middle_initial
middle_name
mobile_phone
name_aliases
num_records
num_sources
operation_id
personal_emails
phone_numbers
phones
possible_birth_dates
possible_emails
possible_location_names
possible_phones
possible_profiles
possible_street_addresses
profiles
recommended_personal_email
regions
skills
street_addresses
summary
twitter_url
twitter_username
work_email
titlecase
Type
Description
Default
Example
Boolean
All text in API responses returns as lowercase by default. Setting titlecase to true will titlecase response data instead.