Input Parameters - Person Enrichment API

Required Parameters

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

TypeDescriptionDefaultExample
StringYour 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.


Optional Parameters

pdl_id

TypeDescriptionExample
StringThe PDL Persistent ID for a record in our Person Dataset.

Note: If you enrich on ID and anything else, only ID is used and the other inputs for matching are ignored.
qEnOZ5Oh0poWnQ1luFBfVw_0000

name

TypeDescriptionExample
StringThe person's full name, at least the first and last.Jennifer C. Jackson

first_name

TypeDescriptionExample
StringThe person's first name.Jennifer

last_name

TypeDescriptionExample
StringThe person's last name.Jackson

middle_name

TypeDescriptionExample
StringThe person's middle name.Cassandra

location

TypeDescriptionExample
StringThe location where a person lives. This can be anything from a street address to a country name.Medford, OR USA

street_address

TypeDescriptionExample
StringThe street address where the person lives.1234 Main Street

locality

TypeDescriptionExample
StringThe locality where the person lives.Boise

region

TypeDescriptionExample
StringThe state or region where the person lives.Idaho

country

TypeDescriptionExample
StringThe country where the person lives.United States

postal_code

TypeDescriptionExample
StringThe postal code where the person lives. If there is no value for country, the postal code is assumed to be US.83701

company

TypeDescriptionExample
StringThe name, website, or social URL of a company where the person has worked.Amazon

school

TypeDescriptionExample
StringThe name, website or social URL of a university or college the person has attended.University of Iowa

phone

TypeDescriptionExample
StringA phone number the person has used. For best results, use +[country code].+1 555-234-1234

email

TypeDescriptionExample
StringAn email the person has used.[email protected]

email_hash

TypeDescriptionExample
StringThe SHA-256 or MD5 email hash.e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4

profile

TypeDescriptionExample
StringA social profile that the person has used (see list of available social profiles).https://linkedin.com/in/seanthorne

lid

TypeDescriptionExample
StringThe person's LinkedIn ID.145991517

birth_date

TypeDescriptionExample
StringThe person's birth date: either the year or a full birth date in the format YYYY-MM-DD.1996-10-01

data_include

TypeDescriptionDefaultExample
StringA 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

TypeDescriptionDefaultExample
BooleanWhether the output should have human-readable indentation.falsetrue

min_likelihood

TypeDescriptionDefaultExample
IntegerThe minimum likelihood score that a response must have in order to count as a match.26

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

TypeDescriptionDefaultExample
BooleanIf true, the response will include the top-level field matched that contains a list of every query input that matched this profile.falsetrue

As an example, if we wanted to enrich Sean Thorne using the following query:

{
   "first_name": "sean",
   "last_name": "thorne",
   "company": "people data labs",
   "location": "abu dhabi",
   "include_if_matched": true
}

Since Sean's location is in California and not Abu Dhabi in the dataset, the response would contain:

{
   "matched": [
        "company",
        "name"
    ]
}

required

TypeDescriptionDefaultExample
StringThe 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)
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';

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

TypeDescriptionDefaultExample
BooleanAll text in API responses returns as lowercase by default. Setting titlecase to true will titlecase response data instead.falsetrue

updated_title_roles

TypeDescriptionDefaultExample
BooleanTemporary parameter. Set to true to return the updated taxonomy for job_title_role and job_title_subrole along with the new job_title_class field.falsetrue