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:
Field 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
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.