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

Parameter Name

Required

Description

Example

name

No

The person's full name, at least the first and last.

Jennifer C. Jackson

first_name

Parameter Name

Required

Description

Example

first_name

No

The person's first name.

Jennifer

last_name

Parameter Name

Required

Description

Example

last_name

No

The person's last name.

Jackson

middle_name

Parameter Name

Required

Description

Example

middle_name

No

The person's middle name.

Cassandra

location

Parameter Name

Required

Description

Example

location

No

The location in which a person lives. This can be anything from a street address to a country name.

Medford, OR USA

street_address

Parameter Name

Required

Description

Example

street_address

No

The street address in which the person lives.

1234 Main Street

locality

Parameter Name

Required

Description

Example

locality

No

The locality in which the person lives.

Boise

region

Parameter Name

Required

Description

Example

region

No

The state or region in which the person lives.

Idaho

country

Parameter Name

Required

Description

Example

country

No

The country in which the person lives.

United States

postal_code

Parameter Name

Required

Description

Example

postal_code

No

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

Parameter Name

Required

Description

Example

company

No

The name, website or social URL of a company where the person has worked.

Amazon Web Services

school

Parameter Name

Required

Description

Example

school

No

The name, website or social URL of a university or college the person has attended.

University of Iowa

phone

Parameter Name

Required

Description

Example

phone

No

The phone number the person has used, in any format.

+1 555-234-1234

email

Parameter Name

Required

Description

Example

email

No

The email the person has used.

[email protected]

email_hash

Parameter Name

Required

Description

Example

email_hash

No

The SHA-256 or MD5 email hash.

e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4

profile

Parameter Name

Required

Description

Example

profile

No

The social profile the person has used List of available social profiles.

https://linkedin.com/in/seanthorne

lid

Parameter Name

Required

Description

Example

lid

No

The person's LinkedIn ID.

145991517

birth_date

Parameter Name

Required

Description

Example

birth_date

No

The person's birth date: either the year or a full birth date.

1996-10-01

data_include

Parameter Name

Required

Description

Example

data_include

No

A comma-separated string of fields that you want the response to include. For example, "full_name,emails.address". Begin the string with a - if you want to exclude the specified fields. If you want to exclude all data from being returned, use data_include="".

pretty

Parameter Name

Required

Description

Example

pretty

No

Whether the output should have human-readable indentation.

false

api_key

Parameter Name

Required

Description

Example

api_key

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

Parameter Name

Required

Description

Example

min_likelihood

No

The minimum likelihood score that a response must have to return a 200 status code.

2

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

Parameter Name

Required

Description

Example

include_if_matched

No

If set to true, includes a top-level field called matched (along with data, status and so forth), which includes a value for each queried field parameter that was "matched" during our internal query.

false

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

Parameter Name

Required

Description

Example

required

No

The fields and data points that a response must have to return a 200 status code.

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

Parameter Name

Required

Description

Example

titlecase

No

All text in API responses returns as lowercase by default. Setting titlecase to true will titlecase the Person data in 200 responses.

false



Did this page help you?