Input Parameters - Person Enrichment API
Detailed information on the input parameters used for the Person Enrichment API
Optional Parameters
While all parameters are optional, the minimum combination of data points that 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)
)
name
name
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The person's full name, at least the first and last. |
|
first_name
first_name
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The person's first name. |
|
last_name
last_name
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The person's last name. |
|
middle_name
middle_name
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The person's middle name. |
|
location
location
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The location in which a person lives. This can be anything from a street address to a country name. |
|
street_address
street_address
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The street address in which the person lives. |
|
locality
locality
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The locality in which the person lives. |
|
region
region
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The state or region in which the person lives. |
|
country
country
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The country in which the person lives. |
|
postal_code
postal_code
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The postal code in which the person lives. If there is no value for country, the postal code is assumed to be US. |
|
company
company
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The name, website or social URL of a company where the person has worked. |
|
school
school
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The name, website or social URL of a university or college the person has attended. |
|
phone
phone
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The phone number the person has used, in any format. |
|
email
email
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The email the person has used. |
email_hash
email_hash
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The SHA-256 or MD5 email hash. |
|
profile
profile
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The social profile the person has used List of available social profiles. |
|
lid
lid
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The person's LinkedIn ID. |
|
birth_date
birth_date
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The person's birth date: either the year or a full birth date. |
|
data_include
data_include
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | A comma-separated string of fields that you want the response to include. For example, |
pretty
pretty
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | Whether the output should have human-readable indentation. |
|
api_key
api_key
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | Your API key. Note: You can also provide this in the request header instead, as shown on the Authentication page. |
Additional Parameters
These input parameters are not required but generally transform or control various aspects of the enrichment process, returning matches or formatting results.
min_likelihood
min_likelihood
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The minimum |
|
Setting a min_likelihood
value in the requests allows you to control the specificity of our matches. For use cases that 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 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 200
response returning a higher likelihood score.
Requests made with only a few data points (for example, a name and a 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
.
include_if_matched
include_if_matched
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | If set to |
|
Please note the match object requests for the following 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']
required
required
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | The fields and data points that a response must have to return a |
The required
parameter ensures that you only get charged for responses that have the data fields 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. The value is formatted as a boolean statements.
Examples
The response must contain an email:
required=emails
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 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'
// 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);
});
Valid Required Parameters
Any top-level fields may be specified in the required
parameter. See the example fields in the section 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
titlecase
Parameter Name | Required | Description | Example |
---|---|---|---|
| No | All text in API responses returns as lowercase by default. Setting |
|
Updated 3 months ago