Preview Enrichment API

Overview

The Preview Enrichment API supports our Person Enrichment API by providing a preview of what fields have data in a record.

We’ve heard from many of our users in the lead/candidate search platform market that they often “tease” their users with previews of contact information for a person to incentivize them. The Preview Enrichment API will help solve this problem.

Request Format

The endpoint for the Preview Enrichment API is https://api.peopledatalabs.com/v5/person/enrich/preview.

See Input Parameters - Person Enrichment API for details on the supported parameters. All valid input parameters for the Person Enrichment API will work the same way for the Preview Enrichment API.

Example

import requests, json

# Set your API key
API_KEY = "YOUR API KEY"

# Set the Preview Enrichment API URL
PDL_URL = "https://api.peopledatalabs.com/v5/person/enrich/preview"

# Set the headers
HEADERS = {
    "X-Api-Key": API_KEY
}

# Create a parameters JSON object
PARAMS = {
    "email": ["[email protected]"],
    "min_likelihood": 6
}

# Pass the parameters object to the Person Enrichment API
json_response = requests.get(PDL_URL, headers=HEADERS, params=PARAMS).json()

# Check for successful response
if json_response["status"] == 200:
  record = json_response['data']

  # Save enrichment data to JSON file
  with open("my_pdl_enrichment_preview.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment preview unsuccessful. See error and try again.")
  print("error:", json_response)

curl -X GET -G \
  'https://api.peopledatalabs.com/v5/person/enrich/preview' \
  -H 'X-Api-Key: xxxx' \
  --data-urlencode '[email protected]'

Response Format

The Preview Enrichment API is a wrapper on the Person Enrichment API, meaning it returns all of the same fields as the Person Enrichment API, but with true / false values instead (true meaning we have a value for that field and false meaning we do not have a value for it).

Any nested objects will not be included in the Preview Enrichment response. For example, if a record has data for the education field, the response will have "education": true, but will not list any of the subfields (such as education.major).

To help users know which record they're looking at, the following fields will have the actual data if it exists for the record: id, full_name, gender, linkedin_url, industry, job_title, job_title_levels, job_company_name, job_company_website, location_name. All other fields will have true/false values as described above.

The output is formatted as such:

Field Name	Type	Description
`data`	`Object`	The person response object.
`status`	`Integer`	The HTTP status code.
`likelihood`	`Integer`	The likelihood score.

Full Example Response

{
   "status": 200,
   "likelihood": 6,
   "data": {
       "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
       "full_name": "sean thorne",
       "gender": "male",
       "linkedin_url": "linkedin.com/in/seanthorne",
       "industry": "computer software",
       "job_title": "co-founder and chief executive officer",
       "job_title_role": null,
       "job_title_sub_role": null,
       "job_title_levels": [
           "owner",
           "cxo"
       ],
       "job_company_name": "people data labs",
       "job_company_website": "peopledatalabs.com",
       "location_name": "san francisco, california, united states",
       "birth_date": false,
       "birth_year": true,
       "countries": true,
       "education": true,
       "emails": true,
       "experience": true,
       "facebook_id": true,
       "facebook_url": true,
       "facebook_username": true,
       "first_name": true,
       "github_url": false,
       "github_username": false,
       "interests": true,
       "job_company_facebook_url": true,
       "job_company_founded": true,
       "job_company_id": true,
       "job_company_industry": true,
       "job_company_linkedin_id": true,
       "job_company_linkedin_url": true,
       "job_company_location_address_line_2": true,
       "job_company_location_continent": true,
       "job_company_location_country": true,
       "job_company_location_geo": true,
       "job_company_location_locality": true,
       "job_company_location_metro": true,
       "job_company_location_name": true,
       "job_company_location_postal_code": true,
       "job_company_location_region": true,
       "job_company_location_street_address": true,
       "job_company_size": true,
       "job_company_twitter_url": true,
       "job_last_updated": true,
       "job_start_date": true,
       "last_initial": true,
       "last_name": true,
       "linkedin_id": true,
       "linkedin_username": true,
       "location_address_line_2": false,
       "location_continent": true,
       "location_country": true,
       "location_geo": true,
       "location_last_updated": true,
       "location_locality": true,
       "location_metro": true,
       "location_names": true,
       "location_postal_code": false,
       "location_region": true,
       "location_street_address": false,
       "middle_initial": true,
       "middle_name": true,
       "mobile_phone": true,
       "personal_emails": false,
       "phone_numbers": true,
       "profiles": true,
       "regions": true,
       "skills": true,
       "street_addresses": false,
       "twitter_url": true,
       "twitter_username": true,
       "version_status": true,
       "work_email": true
   },
   "dataset_version": "19.2"
}

Field Availability

The Preview Enrichment API will only return the fields shown in the example response above. Even if you have purchased additional fields or bundles for Person Enrichment, those fields will not show in the Preview Enrichment response.

Errors

If the request encounters an error, it will instead return an Error Response in the format described in Errors.

Access & Billing

The Preview Enrichment API is available for purchase by enterprise Person Enrichment customers. If you’d like access, please reach out to us.