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
(locality OR region OR company OR school OR location OR postal_code)
)
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
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.
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 and input fields. 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:
Field Name
birth_date
education
emails
experience
facebook_id
facebook_username
full_name
gender
github_username
industry
interests
job_company_name
job_title
last_name
linkedin_id
linkedin_username
location_country
location_locality
location_name
location_postal_code
location_region
location_street_address
mobile_phone
personal_emails
phone_numbers
profiles
skills
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.