Overview

This page details the Person Data that we provide through our Person APIs, such as Person Enrichment and Person Search.

• Base Person Fields: Fields available to all customers by default
• Person Risk Attributes: Premium identity-risk-related fields with enhanced tracking and sourcing information
• Premium Resume Fields: Premium resume-related fields, such as raw-text job titles and summary descriptions

For access to fields beyond the Base Person Fields, please speak to one of our data consultants.

📘

Formatting Notes

The dot notation indicates that the field is a key within an object.

For more information about data formatting, see Data Types.

Base Person Fields

These fields are available to all customers by default.

Identifiers

id

Field Details

The ID is a unique, persistent, and hashed value that represents a specific person. See https://docs.peopledatalabs.com/docs/persistent-ids for more information.

🚧

Upcoming Person ID Maximum Length Change in October 2023

We will be adjusting the maximum character length of PDL Persistent Person IDs. We will be launching this change in October 2023 to allow for ample time to adjust any of your processes impacted by this change.

Currently, IDs are 27 characters long. We recommend allowing for a 64 character maximum for our IDs and will not have any IDs beyond this length, but in practice we expect the changes to result in IDs closer to 32 characters in length. Existing IDs will not change or change length. Only newly created IDs will have the new length.

Example

  "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000"

full_name

Field Details

The first and the last name fields appended with a space.

Example

  "full_name": "sean thorne"

first_name

Field Details

The person's first name.

Example

  "first_name": "sean"

middle_initial

Field Details

The first letter of the person's middle name.

Example

  "middle_initial": "f"

middle_name

Field Details

The person's middle name.

Example

  "middle_name": "fong"

last_initial

Field Details

The first letter of the person's last name.

Example

  "last_initial": "t"

last_name

Field Details

The person's last name.

Example

  "last_name": "thorne"

Demographics

gender

Field Details

The value will always be one of our Canonical Genders.

Example

  "gender": "male"

birth_date

Field Details

If this field exists, birth_year will agree with it.

Example

  "birth_date": "1990-12-02"

birth_year

Field Details

The approximated birth year associated with this person profile. If a profile has a birth_date, the birth_year field will match it.

Example

  "birth_year": 1990

Contact Information

mobile_phone

Field Details

The mobile_phone field is generated from a highly confident source of mobile phones. We've hand-validated a sample of these and seen over 90% accuracy.

Example

  "mobile_phone": "+15558675309"

phone_numbers

Field Details

For more detailed metadata on individual phone numbers, see the phones field in our Person Risk Attributes dataset.

Example

  "phone_numbers": [
    "+15558675309"
  ]

emails

Field Details

Each email associated with the person will be added to this list as its own object. The Person Risk Attributes dataset will add more fields per email.

Example

  "emails": [
    {
      "address": "[email protected]",
      "type": "current_professional"
    },
    {
      "address": "[email protected]",
      "type": "personal"
    }
  ]

personal_emails

Field Details

The list of all emails tagged as type = personal.

Example

  "personal_emails": [
    "[email protected]"
  ]

recommended_personal_email

Field Details

This field is generated by analyzing the all of a person's emails in the personal_emails list to identify the best available email.

Through testing, we’ve found that using the email identified in recommended_personal_email versus selecting a random email address from personal_emails resulted in ~37% higher deliverability.

Example

  "recommended_personal_email": "[email protected]"

work_email

Field Details

The value for this field must use valid email address formatting.

Example

  "work_email": "[email protected]"

Location

For more information on our standard location fields, see https://docs.peopledatalabs.com/docs/data-types#locations.

location_name

Example

  "location_name": "berkeley, california, united states"

location_locality

Example

  "location_locality": "berkeley"

location_region

Example

  "location_region": "california"

location_metro

Example

  "location_metro": "san francisco, california"

location_country

Example

  "location_country": "united states"

location_continent

Example

  "location_continent": "north america"

location_street_address

Example

  "location_street_address": "455 fake st"

location_address_line_2

Example

  "location_address_line_2": "apartment 12"

location_postal_code

Example

  "location_postal_code": "94704"

location_geo

Example

  "location_geo": "37.87,-122.27"

location_last_updated

Field Details

An update is the time when either new information is added to the record or existing information is validated.

Example

  "location_last_updated": "2018-11-05"

location_names

Example

  "location_names": [
    "berkeley, california, united states",
    "san francisco, california, united states"
  ]

regions

Example

  "regions": [
    "california, united states"
  ]

countries

Example

  "countries": [
    "united states"
  ]

street_addresses

Field Details

Each address associated with the person will be added to this list as its own object. The Person Risk Attributes dataset will add more fields per address.

For more information about each field, see Common Location Fields

Example

  "street_addresses": [
    {
      "name": "berkeley, california, united states",
      "locality": "berkeley",
      "metro": "san francisco, california",
      "region": "california",
      "country": "united states",
      "continent": "north america",
      "street_address": "455 fake st",
      "address_line_2": "apartment 12",
      "postal_code": "94704",
      "geo": "37.87,-122.27"
    }
  ]

Social Presence

We currently cover person social profiles on our Canonical Profile Networks. All profiles we've found for a person will be added to the profiles list.

Each social profile URL has one or more standard formats that we parse and turn into a standard PDL format for that social URL. We invalidate profiles that have non-valid person stubs (for example, linkedin.com/company), and we also have a blacklist of usernames that we know are invalid.

We do not validate if a URL is valid (that is, whether you can access it) because doing this at scale is considered a Direct Denial of Service (DDoS) attack and/or a form of crawling. This is highly discouraged! We try to mitigate invalid URLs as much as possible by using Entity Resolution (Merging) to link URLs together and then tagging the primary URL at the top level for key networks.

linkedin_url

Example

  "linkedin_url": "linkedin.com/in/seanthorne"

linkedin_username

Example

  "linkedin_username": "seanthorne"

linkedin_id

Example

  "linkedin_id": "145991517"

facebook_url

Example

  "facebook_url": "facebook.com/deseanthorne"

facebook_username

Example

  "facebook_username": "deseanthorne"

facebook_id

Example

  "facebook_id": "1089351304"

twitter_url

Example

  "twitter_url": "twitter.com/seanthorne5"

twitter_username

Example

  "twitter_username": "seanthorne5"

github_url

Example

  "github_url": "github.com/deseanathan_thornolotheu"

github_username

Example

  "github_username": "deseanathan_thornolotheu"

profiles

Field Details

Each profile associated with the person will be added to this list as its own object. The Person Risk Attributes dataset will add more fields per social profile.

Example

  "profiles": [
    {
      "network": "linkedin",
      "id": "145991517",
      "url": "linkedin.com/in/seanthorne",
      "username": "seanthorne"
    }
  ]

Current Job

These fields describe the person's most recent work experience.

job_title

Field Details

The person's current job title.

Example

  "job_title": "co-founder and chief executive officer"

job_title_role

Field Details

The value will be one of our Canonical Job Roles.

Example

  "job_title_role": "operations"

job_title_sub_role

Field Details

The value will be one of our Canonical Job Sub Roles. Each subrole maps to a role. See https://docs.peopledatalabs.com/docs/title-subroles-to-roles for a complete mapping list.

Example

  "job_title_sub_role": "logistics"

job_title_levels

Field Details

Each level in the list will be one of our Canonical Job Title Levels.

Note: The cxo level is a catch-all for "Chief __ Officer" roles, so a CEO, CIO, CTO, etc. will all have job_title_levels: ["cxo"].

Example

  "job_title_levels": ["cxo", "owner"]

job_last_updated

Field Details

An update is the time when either new information is added to the record or existing information is validated.

Example

  "job_last_updated": "2018-11-05"

job_start_date

Example

  "job_start_date": "2015-03"

Current Company

These fields describe the company the person currently works at. These fields will match the corresponding values in our Company Schema and will use the same formatting and parsing logic.

job_company_id

Example

  "job_company_id": "peopledatalabs"

job_company_name

Example

  "job_company_name": "people data labs"

job_company_website

Example

  "job_company_website": "peopledatalabs.com"

job_company_size

Example

  "job_company_size": "51-200"

job_company_founded

Example

  "job_company_founded": 2015

job_company_industry

Example

  "job_company_industry": "computer software"

job_company_linkedin_url

Example

  "job_company_linkedin_url": "linkedin.com/company/peopledatalabs"

job_company_linkedin_id

Example

  "job_company_linkedin_id": "18170482"

job_company_facebook_url

Example

  "job_company_facebook_url": "facebook.com/peopledatalabs"

job_company_twitter_url

Example

  "job_company_twitter_url": "twitter.com/peopledatalabs"

job_company_location_name

Example

  "job_company_location_name": "san francisco, california, united states"

job_company_location_locality

Example

  "job_company_location_locality": "san francisco"

job_company_location_region

Example

  "job_company_location_region": "california"

job_company_location_metro

Example

  "job_company_location_metro": "san francisco, california"

job_company_location_country

Example

  "job_company_location_country": "united states"

job_company_location_continent

Example

  "job_company_location_continent": "north america"

job_company_location_street_address

Example

  "job_company_location_street_address": "455 market st"

job_company_location_address_line_2

Example

  "job_company_location_address_line_2": "suite 1670"

job_company_location_postal_code

Example

  "job_company_location_postal_code": "94105"

job_company_location_geo

Example

  "job_company_location_geo": "37.77,-122.41"

Work History

industry

Field Details

A person's industry is determined based on their tagged personal industries and the industries of the companies that they have worked for.

The value will be one of our Canonical Industries.

Example

  "industry": "computer software"

interests

Field Details

Each interest is cleaned (lowercased, stripped of whitespace, etc.). We don't have a finite lists of interests but we remove profanity, etc.

Example

  "interests": [
    "data"
  ]

skills

Field Details

Each skill is cleaned (lowercased, stripped of whitespace, etc.). We do not always strip punctuation because it can be relevant for some skills (ex: "c++" vs "c").

We do not do any canonicalization, so "java" and "java 8.0" are considered separate skills. For this reason, we encourage our customers to use fuzzy text matching with the skills field.

The Skill Enrichment API can help find similar skills.

Example

  "skills": [
    "entrepreneurship"
  ]

experience

Field Details

The order of work experience in the list is determined by recency and associativity. The experience object that is tagged as experience.is_primary = True is copied over to the flattened job_ fields (see Current Job and Current Company).

The Person Risk Attributes dataset will add more fields per work experience.

Each work experience object contains the following fields:

experience.company

The fields in experience.company map to the corresponding fields in our Company Schema. The same parsing and formatting logic apply.

experience.title

See Current Job for more details on the specific fields.

Example

  "experience": [
    {
      "company": {
        "name": "people data labs",
        "size": "11-50",
        "id": "peopledatalabs",
        "founded": 2015,
        "industry": "computer software",
        "location": {
          "name": "san francisco, california, united states",
          "locality": "san francisco",
          "region": "california",
          "metro": "san francisco, california",
          "country": "united states",
          "continent": "north america",
          "street_address": "455 market street",
          "address_line_2": "suite 1670",
          "postal_code": "94105",
          "geo": "37.77,-122.41"
        },
        "linkedin_url": "linkedin.com/company/peopledatalabs",
        "linkedin_id": "18170482",
        "facebook_url": "facebook.com/peopledatalabs",
        "twitter_url": "twitter.com/peopledatalabs",
        "website": "peopledatalabs.com"
      },
      "location_names": ["san francisco, california, united states"],
      "end_date": null,
      "start_date": "2015-03",
      "title": {
        "name": "chief executive officer and co-founder",
        "role": "operations",
        "sub_role": "logistics",
        "levels": ["cxo", "owner"]
      },
      "is_primary": true
    },
  ]

Education

education

Field Details

The education objects associated with this person profile, which, when output in CSV format, have indexing based on recency and associativity.

Each education object in the list will include the following data:

education.school

To tap into our school matching logic, use our School Cleaner API to retrieve possible school values.

Example

  "education": [
    {
      "school": {
        "name": "university of oregon",
        "type": "post-secondary institution",
        "id": "64LkgfdwWYkCC2TjbldMDQ_0",
        "location": {
          "name": "eugene, oregon, united states",
          "locality": "eugene",
          "region": "oregon",
          "country": "united states",
          "continent": "north america"
        },
        "linkedin_url": "linkedin.com/school/university-of-oregon",
        "linkedin_id": "19207",
        "facebook_url": "facebook.com/universityoforegon",
        "twitter_url": "twitter.com/uoregon",
        "website": "uoregon.edu",
        "domain": "uoregon.edu"
      },
      "end_date": "2014",
      "start_date": "2010",
      "gpa": null,
      "degrees": [],
      "majors": [
        "entrepreneurship"
      ],
      "minors": []
    },
  ]

Metadata

operation_id

Field Details

This field exists only in Data License deliveries, and allows PDL employees to identify the timestamp and operations performed on the internal data in order to return a record in a delivery.

Example

  "operation_id": "acee3bde2e1a2cb7e75c57b80d5b7bc2d5de5b02e7ea51f91304c28df77251dc"

dataset_version

Field Details

This field currently exists in Person Enrichment API responses only.

Note: This number corresponds to the data release number, not the API release number.

Example

  "dataset_version": "19.2"

version_status

❗️

DEPRECATION NOTICE

This object has been deprecated in API responses.

Field Details

This object tracks the pervious and current dataset version, and any other persistent IDs that were merged into this record using improved entity resolution and the status of the record.

Example

  "version_status": {
    "contains": [
      "qEnOZ5Oh0poWnQ1luFBfVw_0000"
    ],
    "current_version": "15",
    "previous_version": "14",
    "status": "updated"
  }

Person Risk Attributes

These are premium identity-risk-related fields with enhanced tracking and sourcing information.

Additional Subfields

The subfields are available for every record in the following fields:

• emails
• experience
• profiles
• street_addresses

Example

  "profiles // emails // experience // street_addresses": [
    {
      ...
      "first_seen": "2017-06-02",
      "last_seen": "2019-07-18",
      "num_sources": 17
    }
  ]

Contact Information

phones

Field Details

Each phone number object in this list will contain the following information.

Example

  "phones": [
    {
      "number": "+15558675309",
      "first_seen": "2017-06-02",
      "last_seen": "2019-07-18",
      "num_sources": 17   
    }
  ]

linkedin_connections

Field Details

Typically between 0-500.

Example

  "linkedin_connections": 432

facebook_friends

Example

  "facebook_friends": 3912

name_aliases

Field Details

Any associated names or aliases besides the primary one used in the full_name field.

Example

  "name_aliases": [
    "andrew nichol",
    "r andrew nichol",
    "robert nichol"
  ]

Lower Confidence Data

PDL values high confidence data that is very likely to be associated with a person. The data in these fields have lower confidence than the data used in other fields.

possible_emails

Field Details

This field uses the same format as the emails field, including first_seen, last_seen, and num_sources.

Example

  "possible_emails": [
    {
      "address": "[email protected]",
      "type": null,
      "first_seen": "2021-06-13",
      "last_seen": "2021-06-13",
      "num_sources": 2
    }
  ]

possible_phones

Field Details

This field uses the same format as the phones field, including first_seen, last_seen, and num_sources.

Example

  "possible_phones": [
    {
      "number": "+15558675309",
      "first_seen": "2021-06-13",
      "last_seen": "2021-06-13",
      "num_sources": 2
    }
  ]    

possible_profiles

Field Details

This field uses the same format as the profiles field, including first_seen, last_seen, and num_sources.

Example

  "possible_profiles": [
    {
      "network": "linkedin",
      "id": "145991517",
      "url": "linkedin.com/in/seanthorne",
      "username": "seanthorne",
      "first_seen": "2021-06-13",
      "last_seen": "2021-06-13",
      "num_sources": 2
    }
  ]

possible_street_addresses

Field Details

This field uses the same format as the street_addresses field, including first_seen, last_seen, and num_sources.

Example

  "possible_street_addresses": [
    {
      "name": "berkeley, california, united states",
      "locality": "berkeley",
      "metro": "san francisco, california",
      "region": "california",
      "country": "united states",
      "continent": "north america",
      "street_address": "455 fake st",
      "address_line_2": "apartment 12",
      "postal_code": "94704",
      "geo": "37.87,-122.27",
      "first_seen": "2021-06-13",
      "last_seen": "2021-06-13",
      "num_sources": 2
    }
  ]

possible_birth_dates

Field Details

The dates in this field use the same format as the birth_date field.

Example

  "possible_birth_dates": [
    "1991-05-26",
    "1992-05-26"
  ]

possible_location_names

Field Details

This field uses the same format as the location_names field.

Possible locations are inferred based on phone area codes, university location, and other associations.

Example

  "possible_location_names": [
    "berkeley, california, united states",
    "san francisco, california, united states"
  ]

Job History

job_history

Field Details

Any additional job history information PDL has that is not included in the experience field.

Usually these are positions that have been removed or changed on resumes.

Example

  "job_history": [
    {
      "company_id": "auntie-annes",
      "company_name": "auntie annes",
      "title": "food service supervisor",
      "first_seen": "2016-05-17",
      "last_seen": "2020-05-30",
      "num_sources": 12
    }
  ]

PDL Record Information

num_records

Example

  "num_records": 420

num_sources

Example

  "num_sources": 72

first_seen

Example

  "first_seen": "2017-06-02"

Premium Resume Fields

These are premium resume-related fields.

Raw Input

These fields contain the raw input used in other fields.

education.raw

Field Details

Raw education data that was parsed into the degrees, majors, and minors fields in the education object.

Example

  "education": [
    {
      ...
      "raw": "bachelors of arts in entrepreneurship, business minor"
    }
  ]

education.school.raw

Field Details

Raw school name used to populate the education.school object.

Example

  "education": [
    {
      "school": {
        ...
        "raw": "university of oregon"  
      }
    }
  ]

experience.company.raw

Field Details

Raw company name(s) used to populate the experience.company object.

Example

  "experience": [
    {
      "company": {
        ...
        "raw": [
          "hallspot",
          "hallspot, inc"
        ]
      }
    }
  ]

experience.title.raw

Field Details

The lower cased job title raw input from our data sources used to populate the experience.title object.

Example

  "experience": [
    {
      "title": {
        ...
        "raw": [
          "chief executive officer and co-founder"
        ]
      }
    }
  ]

Summaries

These fields contain the user-inputted summaries for their experiences.

education.summary

Field Details

The summary is lowercased, but otherwise kept as-is from the raw source.

Example

  "education": [
    {
      ...
      "summary": "when i was at oregon i volunteered at a local homeless shelter 3 days a week"
    }
  ]

experience.summary

Field Details

The summary is lowercased, but otherwise kept as-is from the raw source.

Example

  "experience": [
    {
      ...
      "summary": "worked on the \"search analytics\" team to understand our users better"
    }
  ]

job_summary

Field Details

The summary is lowercased, but otherwise kept as-is from the raw source.

Example

  "job_summary": "worked on the \"search analytics\" team to understand our users better"

summary

Field Details

The self-written summary tied to the person profile (often a LinkedIn summary.)

The summary is lowercased, but otherwise kept as-is from the raw source.

Example

  "summary": "growth-hacker and digital nomad"

Certifications & Languages

certifications

Field Details

The certifications listed here are based on user input, we do not verify them.

Example

  "certifications": [
    {
      "name": "machine learning certification",
      "organization": "coursera",
      "start_date": "2022-03",
      "end_date": "2023-04"
    }
  ]

languages

Field Details

The languages listed here are based on user input, we do not verify them.

Example

  "languages": [
    {
      "name": "english",
      "proficiency": 5
    }
  ]

Company Stock Information

experience.company.ticker

Field Details

Corresponds to the Company Data ticker field.

Example

  "experience": [
    {
      "company": {
        ...
        "ticker": "goog"
      }
    }
  ]

experience.company.type

Field Details

Must be one of our Canonical Company Types. Corresponds to the Company Data type field.

Example

  "experience": [
    {
      "company": {
        ...
        "type": "public"
      }
    }
  ]

job_company_ticker

Field Details

Corresponds to the Company Data ticker field.

Example

  "job_company_ticker": "goog"

job_company_type

Field Details

Must be one of our Canonical Company Types. Corresponds to the Company Data type field.

Example

  "job_company_type": "public"

O*NET Code

job_onet_code

Field Details

The 8-digit O*NET code for the person’s current job title, following the 2018 SOC guidelines.

Example

  "job_onet_code": "11-1011.00"

job_onet_major_group

Example

  "job_onet_major_group": "Management Occupations"

job_onet_minor_group

Example

  "job_onet_minor_group": "Top Executives"

job_onet_broad_occupation

Example

  "job_onet_broad_occupation": "Chief Executives"

job_onet_specific_occupation

Example

  "job_onet_specific_occupation": "Chief Executives"

job_onet_specific_occupation_detail

Field Details

A more detailed job title for records where the specific occupation within O*NET's standard hierarchy isn't granular enough to accurately describe the job title.

For example, the highest level of granularity in O*NET for C-suite positions is Chief Executives. With this field, we can specify the type of executive role.

Example

  "job_onet_specific_occupation_detail": "Chief Technology Officer"

Inferred & Calculated Values

inferred_salary

Field Details

Must be one of our Canonical Inferred Salary Ranges.

Example

  "inferred_salary": "70,000-85,000"

inferred_years_experience

Field Details

The value will be between 0 and 100.

Example

  "inferred_years_experience": 7