Input Parameters - Person Enrichment API - People Data Labs Documentation

Request Requirements

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.

Optional Request Parameters

`pdl_id`

Type	Description	Example
`String`	The 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`

Type	Description	Example
`String`	The person’s full name, at least the first and last.	`Jennifer C. Jackson`

`first_name`

Type	Description	Example
`String`	The person’s first name.	`Jennifer`

`last_name`

Type	Description	Example
`String`	The person’s last name.	`Jackson`

`middle_name`

Type	Description	Example
`String`	The person’s middle name.	`Cassandra`

`location`

Type	Description	Example
`String`	The location where a person lives. This can be anything from a street address to a country name.	`Medford, OR USA`

`street_address`

Type	Description	Example
`String`	The street address where the person lives.	`1234 Main Street`

`locality`

Type	Description	Example
`String`	The locality where the person lives.	`Boise`

`region`

Type	Description	Example
`String`	The state or region where the person lives.	`Idaho`

`country`

Type	Description	Example
`String`	The country where the person lives.	`United States`

`postal_code`

Type	Description	Example
`String`	The postal code where the person lives. If there is no value for country, the postal code is assumed to be US.	`83701`

`company`

Type	Description	Example
`String`	The name, website, or social URL of a company where the person has worked.	`Amazon`

`school`

Type	Description	Example
`String`	The name, website or social URL of a university or college the person has attended.	`University of Iowa`

`phone`

Type	Description	Example
`String`	A phone number the person has used. Input must begin with `+[country code]` for a match to be returned.	`+1 555-234-1234`

`email`

Type	Description	Example
`String`	An email the person has used.	`renee.c.paulsen1959@yahoo.com`

`email_hash`

Type	Description	Example
`String`	The SHA-256 or MD5 email hash.	`e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4`

`profile`

Type	Description	Example
`String`	A social profile that the person has used (see list of available social profiles).	`https://linkedin.com/in/seanthorne`

`lid`

Type	Description	Example
`String`	The person’s LinkedIn ID.	`145991517`

`birth_date`

Type	Description	Example
`String`	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:

JSON

{
   "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:

JSON

{
   "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:

cURL

required=linkedin_url

The response must contain experience and a current work email:

cURL

required=experience AND work_email

The response must contain experience or emails:

cURL

required=experience OR emails

The response must contain education and either emails or phone_numbers:

cURL

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:

You must have access to the appropriate Person Data Field Bundle for any field you provide as a required parameter.

Field Name
`birth_date`
`birth_year`
`certifications`
`countries`
`dataset_version`
`education`
`emails`
`experience`
`facebook_friends`
`facebook_id`
`facebook_url`
`facebook_username`
`first_name`
`first_seen`
`full_name`
`sex`
`github_url`
`github_username`
`headline`
`id`
`industry`
`inferred_salary`
`inferred_years_experience`
`interests`
`job_company_12mo_employee_growth_rate`
`job_company_employee_count`
`job_company_facebook_url`
`job_company_founded`
`job_company_id`
`job_company_industry`
`job_company_inferred_revenue`
`job_company_linkedin_id`
`job_company_linkedin_url`
`job_company_location_address_line_2`
`job_company_location_continent`
`job_company_location_country`
`job_company_location_geo`
`job_company_location_locality`
`job_company_location_metro`
`job_company_location_name`
`job_company_location_postal_code`
`job_company_location_region`
`job_company_location_street_address`
`job_company_name`
`job_company_size`
`job_company_ticker`
`job_company_total_funding_raised`
`job_company_twitter_url`
`job_company_type`
`job_company_website`
`job_history`
`job_last_changed`
`job_last_verified`
`job_onet_broad_occupation`
`job_onet_code`
`job_onet_major_group`
`job_onet_minor_group`
`job_onet_specific_occupation`
`job_onet_specific_occupation_detail`
`job_start_date`
`job_summary`
`job_title`
`job_title_levels`
`job_title_role`
`job_title_sub_role`
`job_title_class`
`languages`
`last_initial`
`last_name`
`linkedin_connections`
`linkedin_id`
`linkedin_url`
`linkedin_username`
`location_address_line_2`
`location_continent`
`location_country`
`location_geo`
`location_last_updated`
`location_locality`
`location_metro`
`location_name`
`location_names`
`location_postal_code`
`location_region`
`location_street_address`
`middle_initial`
`middle_name`
`mobile_phone`
`name_aliases`
`num_records`
`num_sources`
`operation_id`
`personal_emails`
`phone_numbers`
`phones`
`possible_birth_dates`
`possible_emails`
`possible_location_names`
`possible_phones`
`possible_profiles`
`possible_street_addresses`
`profiles`
`recommended_personal_email`
`regions`
`skills`
`street_addresses`
`summary`
`twitter_url`
`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.	`false`	`true`

​Request Requirements

​api_key

​Optional Request Parameters

​pdl_id

​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

​min_likelihood

​include_if_matched

​required

​titlecase

Request Requirements

`api_key`

Optional Request Parameters

`pdl_id`

`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`

`min_likelihood`

`include_if_matched`

`required`

`titlecase`