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

first_name

last_name

middle_name

location

street_address

locality

region

country

postal_code

company

school

phone

email

email_hash

profile

lid

birth_date

data_include

pretty

api_key

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

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

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

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:

titlecase