Person Schema

A breakdown of the person-related fields we offer

Overview

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

📘

Field Availability

Please note: Not all fields are available in all bundles.


Identifiers

first_name

Description The person's first name.
Data Type String

Field Details

The person's first name.

Example

  "first_name": "sean"

full_name

Description The person's full name.
Data Type String

Field Details

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

Example

  "full_name": "sean thorne"

id

Description A unique persistent identifier for the person.
Data Type String

Field Details

The ID is a unique, persistent, and hashed value that represents a specific person.

As of v24, IDs have a max length of 64 characters, although in practice we expect IDs to be closer to 32 characters in length.

See https://docs.peopledatalabs.com/docs/persistent-ids for more information.

Example

  "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000"

last_initial

Description The first letter of the person's last name.
Data Type String (1 character)

Field Details

The first letter of the person's last name.

Example

  "last_initial": "t"

last_name

Description The person's last name.
Data Type String

Field Details

The person's last name.

Example

  "last_name": "thorne"

middle_initial

Description The first letter of the person's middle name.
Data Type String (1 character)

Field Details

The first letter of the person's middle name.

Example

  "middle_initial": "f"

middle_name

Description The person's middle name.
Data Type String

Field Details

The person's middle name.

Example

  "middle_name": "fong"

name_aliases

Description Any other names the person goes by.
Data Type Array [String]

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"
  ]

Contact Information

emails

Description Email addresses associated with the person.
Data Type Array [Object]

Field Details

Each email associated with the person will be added to this list as its own object.

FieldData TypeDescription
addressStringThe fully parsed email address
first_seenString (Date)The date that this entity was first associated with the Person record.
last_seenString (Date)The date that this entity was last associated with the Person record.
num_sourcesInteger (> 0)The number of sources that have contributed to the association of this entity with the Person record.
typeEnum (String)The type of email address. Must be one of our Canonical Email Types

Example

  "emails": [
    {
      "address": "[email protected]",
      "type": "current_professional",
      "first_seen": "2017-06-02",
      "last_seen": "2019-07-18",
      "num_sources": 17
    },
    {
      "address": "[email protected]",
      "type": "personal",
      "first_seen": "2017-06-02",
      "last_seen": "2019-07-18",
      "num_sources": 17
    }
  ]

mobile_phone

Description The person's mobile phone number.
Data Type String (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"

personal_emails

Description All personal emails associated with the person.
Data Type Array [String]

Field Details

The list of all emails tagged as type = personal.

Example

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

phone_numbers

Description All phone numbers associated with the person.
Data Type Array [String (Phone)]

Field Details

For more detailed metadata on individual phone numbers, see the phones field.

Example

  "phone_numbers": [
    "+15558675309"
  ]

phones

Description The list of phone numbers associated with this record with additional metadata.
Data Type Array [Object]

Field Details

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

FieldData TypeDescription
first_seenString (Date)The date that this number was first associated with this record.
last_seenString (Date)The date that this number was last associated with this record.
num_sourcesInteger (> 0)The number of sources that have contributed to the association of this profile with this record.
numberString (Phone)The phone number.

Example

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

recommended_personal_email

Description The best available email to reach a person.
Data Type String

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

Description The person's current work email.
Data Type String

Field Details

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

Example

  "work_email": "[email protected]"

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_12mo_employee_growth_rate

Description The person’s current company’s percentage increase in total headcount over the past 12 months. Mapped from employee_growth_rate.12_month.

Growth rate is calculated as (current_employee_count / previous_employee_count) - 1.
Data Type Float

Example

  "job_company_12mo_employee_growth_rate": -0.1379

job_company_facebook_url

Description The person's current company's Facebook URL.
Data Type String

Example

  "job_company_facebook_url": "facebook.com/peopledatalabs"

job_company_founded

Description The person's current company's founding year.
Data Type Integer (> 0)

Example

  "job_company_founded": 2015

job_company_employee_count

Description The total number of PDL profiles associated with the person’s current company. Mapped from employee_count.
Data Type Integer (>= 0)

Example

  "job_company_employee_count": 125

job_company_id

Description The person's current company's PDL ID.
Data Type String

Example

  "job_company_id": "tnHcNHbCv8MKeLh92946LAkX6PKg"

job_company_industry

Description The person's current company's industry.
Data Type Enum (String)

Example

  "job_company_industry": "computer software"

job_company_inferred_revenue

Description The estimated annual revenue range in USD of the person’s current company.
Data Type Enum (String)

Example

  "job_company_inferred_revenue": "$25M-$50M"

job_company_linkedin_id

Description The person's current company's LinkedIn ID.
Data Type String

Example

  "job_company_linkedin_id": "18170482"

job_company_linkedin_url

Description The person's current company's LinkedIn URL.
Data Type String

Example

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

job_company_location_address_line_2

Description The person's current company's headquarters' street address line 2.
Data Type String

Example

  "job_company_location_address_line_2": "suite 1670"

job_company_location_continent

Description The person's current company's headquarters' continent.
Data Type Enum (String)

Example

  "job_company_location_continent": "north america"

job_company_location_country

Description The person's current company's headquarters' country.
Data Type Enum (String)

Example

  "job_company_location_country": "united states"

job_company_location_geo

Description The person's current company's headquarters' city-center geographic coordinates.
Data Type String

Example

  "job_company_location_geo": "37.77,-122.41"

job_company_location_locality

Description The person's current company's headquarters' locality.
Data Type String

Example

  "job_company_location_locality": "san francisco"

job_company_location_metro

Description The person's current company's headquarters' metro area.
Data Type Enum (String)

Example

  "job_company_location_metro": "san francisco, california"

job_company_location_name

Description The person's current company's headquarters' location name.
Data Type String

Example

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

job_company_location_postal_code

Description The person's current company's headquarters' postal code.
Data Type String

Example

  "job_company_location_postal_code": "94105"

job_company_location_region

Description The person's current company's headquarters' region.
Data Type String

Example

  "job_company_location_region": "california"

job_company_location_street_address

Description The person's current company's headquarters' street address.
Data Type String

Example

  "job_company_location_street_address": "455 market st"

job_company_name

Description The person's current company's name.
Data Type String

Example

  "job_company_name": "people data labs"

job_company_size

Description The person's current company's size range.
Data Type Enum (String)

Example

  "job_company_size": "51-200"

job_company_ticker

Description The person's current company's ticker.
Data Type String

Example

  "job_company_ticker": "goog"

job_company_total_funding_raised

Description The cumulative amount of money raised in USD by the person’s current company during all publicly disclosed funding rounds.
Data Type Integer (> 0)

Example

  "job_company_total_funding_raised": 55250000.0

job_company_twitter_url

Description The person's current company's Twitter URL.
Data Type String

Example

  "job_company_twitter_url": "twitter.com/peopledatalabs"

job_company_type

Description The person's current company's type.
Data Type Enum (String)

Example

  "job_company_type": "public"

job_company_website

Description The person's current company's website.
Data Type String

Example

  "job_company_website": "peopledatalabs.com"

Current Job

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

inferred_salary

Description The inferred salary range (USD) for the person's current job.
Data Type Enum (String)

Field Details

Must be one of our Canonical Inferred Salary Ranges.

Example

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

job_last_updated

❗️

job_last_updated is being deprecated in v27.0

In v26.0 (April 2024), we released 2 new fields job_last_verified and job_last_changed intended to fully replace the functionality of the job_last_updated field, which will be removed from the Person Schema in v27.0 (July 2024).

For further information and guidance on transitioning to these new fields, please see our April 2024 Release Announcement (v26.0).

Description The timestamp that a new data source contributed to the record for the person's current job.
Data Type String (Date)

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_last_changed

Description The timestamp that reflects when the top-level job information changed.
Data Type String (Date)

Field Details

An update is the time when the current employment information is modified in the record.

🚧

Limitations of Observed Data

This field reflects observed data. This means that this timestamp will reflect the date when updates were propagated into our data build from our data sources, and may contain some lag time compared to real-life events. For example, if User A changed their job on October 1, 2023, but did not update that publicly until December 1, 2023, our timestamp for job_last_changed will be December.

Example

  "job_last_changed": "2023-12-01"

job_last_verified

Description The timestamp that reflects when the top level job information was last validated by a data source.
Data Type String (Date)

Field Details

An update is the time when the information in a record is validated through a data source. For more information how this timestamp is generated see: Experience & Location Updates

Example

  "job_last_verified": "2024-01-05"

job_onet_broad_occupation

Description The O*NET Broad Occupation associated with the person’s current job title.
Data Type String

Example

  "job_onet_broad_occupation": "Chief Executives"

job_onet_code

Description The 8-digit O*NET code for the person’s current job title.
Data Type String

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

Description The O*NET Major Group associated with the person’s current job title.
Data Type String

Example

  "job_onet_major_group": "Management Occupations"

job_onet_minor_group

Description The O*NET Minor Group associated with the person’s current job title.
Data Type String

Example

  "job_onet_minor_group": "Top Executives"

job_onet_specific_occupation

Description The O*NET Specific Occupation associated with the person’s current job title.
Data Type String

Example

  "job_onet_specific_occupation": "Chief Executives"

job_onet_specific_occupation_detail

Description A more detailed job title classification than O*NET Specific Occupation.
Data Type String

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"

job_start_date

Description The date the person started their current job.
Data Type String (Date)

Example

  "job_start_date": "2015-03"

job_summary

Description User-inputted summary of their current job.
Data Type String

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"

job_title

Description The person's current job title.
Data Type String

Field Details

The person's current job title.

Example

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

job_title_levels

Description The derived level(s) of the person's current job title.
Data Type Array [Enum (String)]

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_title_role

Description The derived role of the person's current job title.
Data Type Enum (String)

Field Details

The value will be one of our Canonical Job Roles.

🚧

Major Improvements Scheduled for v28.0 (October 2024)

In v28.0 (October 2024) we will be making significant improvements to our role and sub_role categorizations and changing the canonical values associated with these fields.

Please see our April 2024 Release Announcement (v26.0) for further information.

Example

  "job_title_role": "operations"

job_title_sub_role

Description The derived subrole of the person's current job title.
Data Type Enum (String)

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.

🚧

Major Improvements Scheduled for v28.0 (October 2024)

In v28.0 (October 2024) we will be making significant improvements to our role and sub_role categorizations and changing the canonical values associated with these fields.

Please see our April 2024 Release Announcement (v26.0) for further information.

Example

  "job_title_sub_role": "logistics"

Demographics

birth_date

Description The day the person was born.
Data Type String (Date)

Field Details

If this field exists, birth_year will agree with it.

Example

  "birth_date": "1990-12-02"

birth_year

Description The year the person was born.
Data Type Integer

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

sex

🚧

gender was renamed to sex in v26.0

In v26.0 (April 2024) we renamed this field from gender to sex, in accordance with legislative changes defining aspects of gender as sensitive personal data (which PDL does not process or output).

Please see our April 2024 Release Announcement (v26.0) for further information.

Description The person's sex.
Data Type Enum (String)

Field Details

The value will always be one of our Canonical Sex.

Example

  "sex": "male"

languages

Description Languages the person knows.
Data Type Array [Object]

Field Details

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

FieldData TypeDescription
nameEnum (String)The language. Must be one of our Canonical Languages.
proficiencyInteger (1-5)Self-ranked language proficiency from 1 (limited) to 5 (fluent).

Example

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

Education

education

Description The person's education information.
Data Type Array [Object]

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:

FieldData TypeDescription
degreesArray [Enum (String)]The degrees the person earned at the school. All values will be Canonical Education Degrees
end_dateString (Date)The date the person left the school. If the person is still at the school, will be null.
gpaFloatThe GPA the person earned at the school.
majorsArray [Enum (String)]All majors earned at the school. All values will be Canonical Education Majors.
minorsArray [Enum (String)]All minors earned at the school. All values will be Canonical Education Majors.
rawArray [String]Raw education data that was parsed into the degrees, majors, and minors fields.
schoolObjectThe school the person attended.
start_dateString (Date)The date the person started at the school.
summaryStringUser-inputted summary of their education.
education.school

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

FieldSub FieldData TypeDescription
domainStringThe primary website domain associated with the school.
facebook_urlStringThe school's Facebook URL
idStringThe NON-PERSISTENT ID for the school in our records.
linkedin_idStringThe school's LinkedIn ID
linkedin_urlStringThe school's LinkedIn URL
locationObjectThe location of the school. See Common Location Fields for detailed field descriptions.
continentEnum (String)
countryEnum (String)
localityString
nameString
regionString
nameStringThe name of the school.
rawArray [String]Raw school name.
twitter_urlStringThe school's Twitter URL
typeEnum (String)The school type. Will be one of our Canonical School Types.
websiteStringThe website URL associated with the school, which could include subdomains.

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",
        "raw": [
          "university of oregon"
        ]
      },
      "end_date": "2014",
      "start_date": "2010",
      "gpa": null,
      "degrees": [],
      "majors": [
        "entrepreneurship"
      ],
      "minors": [],
      "raw": [
        "data analytics & entrepreneurship",
        ", entrepreneurship",
        "entrepreneurship"
      ],
      "summary": "when i was at oregon i volunteered at a local homeless shelter 3 days a week"
    },
  ]

Location

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

countries

Description All countries associated with the person.
Data Type Array [Enum (String)]

Example

  "countries": [
    "united states"
  ]

location_address_line_2

Description The person's current street address line 2.
Data Type String

Example

  "location_address_line_2": "apartment 12"

location_continent

Description The continent of the person's current address. One of our Canonical Continents.
Data Type Enum (String)

Example

  "location_continent": "north america"

location_country

Description The country of the person's current address. One of our Canonical Countries.
Data Type Enum (String)

Example

  "location_country": "united states"

location_geo

Description The geo code of the city center of the person's current address.
Data Type String

Example

  "location_geo": "37.87,-122.27"

location_last_updated

Description The timestamp that a new data source contributed to the record for the person's current address.
Data Type String (Date)

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_locality

Description The locality of the person's current address.
Data Type String

Example

  "location_locality": "berkeley"

location_metro

Description The metro of the person's current address. One of our Canonical Metros.
Data Type Enum (String)

Example

  "location_metro": "san francisco, california"

location_name

Description The location of the person's current address.
Data Type String

Example

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

location_names

Description All location names associated with the person.
Data Type Array [String]

Example

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

location_postal_code

Description The postal code of the person's current address.
Data Type String

Example

  "location_postal_code": "94704"

location_region

Description The region of the person's current address.
Data Type String

Example

  "location_region": "california"

location_street_address

Description The person's current street address.
Data Type String

Example

  "location_street_address": "455 fake st"

regions

Description All regions associated with the person.
Data Type Array [String]

Example

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

street_addresses

Description All street addresses associated with the person.
Data Type Array [Object]

Field Details

Each address associated with the person will be added to this list as its own object.

In addition to the Common Location Fields, street_addresses will also include:

FieldData TypeDescription
first_seenString (Date)The date that this entity was first associated with the Person record.
last_seenString (Date)The date that this entity was last associated with the Person record.
num_sourcesInteger (> 0)The number of sources that have contributed to the association of this entity with the Person record.

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",
      "first_seen": "2017-06-02",
      "last_seen": "2019-07-18",
      "num_sources": 17
    }
  ]

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_birth_dates

Description Birthdays associated with this person that have a lower level of confidence.
Data Type Array [String (Date)]

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_emails

Description Email addresses associated with this person that have a lower level of confidence.
Data Type Array [Object]

Field Details

This field uses the same format as the emails field.

Example

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

possible_location_names

Description Locations associated with this person that have a lower level of confidence.
Data Type Array [String]

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"
  ]

possible_phones

Description Phone numbers associated with this person that have a lower level of confidence.
Data Type Array [Object]

Field Details

This field uses the same format as the phones field.

Example

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

possible_profiles

Description Social profiles associated with this person that have a lower level of confidence.
Data Type Array [Object]

Field Details

This field uses the same format as the profiles field.

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

Description Addresses associated with this person that have a lower level of confidence.
Data Type Array [Object]

Field Details

This field uses the same format as the street_addresses field.

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
    }
  ]

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.

facebook_friends

Description The number of Facebook friends the person has.
Data Type Integer (>= 0)

Example

  "facebook_friends": 3912

facebook_id

Description The person's Facebook profile ID based on source agreement.
Data Type String

Example

  "facebook_id": "1089351304"

facebook_url

Description The person's Facebook profile URL based on source agreement.
Data Type String

Example

  "facebook_url": "facebook.com/deseanthorne"

facebook_username

Description The person's Facebook profile username based on source agreement.
Data Type String

Example

  "facebook_username": "deseanthorne"

github_url

Description The person's GitHub profile URL based on source agreement.
Data Type String

Example

  "github_url": "github.com/deseanathan_thornolotheu"

github_username

Description The person's GitHub profile username based on source agreement.
Data Type String

Example

  "github_username": "deseanathan_thornolotheu"

linkedin_connections

Description The number of LinkedIn connections the person has.
Data Type Integer (>= 0)

Field Details

Typically between 0-500.

Example

  "linkedin_connections": 432

linkedin_id

Description The person's LinkedIn profile ID based on source agreement.
Data Type String

Example

  "linkedin_id": "145991517"

linkedin_url

Description The person's LinkedIn profile URL based on source agreement.
Data Type String

Example

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

linkedin_username

Description The person's LinkedIn profile username based on source agreement.
Data Type String

Example

  "linkedin_username": "seanthorne"

profiles

Description Social profiles associated with the person.
Data Type Array [Object]

Field Details

Each profile associated with the person will be added to this list as its own object.

FieldData TypeDescription
idStringThe profile ID (format varies based on social network).
first_seenString (Date)The date that this entity was first associated with the Person record.
last_seenString (Date)The date that this entity was last associated with the Person record.
networkEnum (String)The social network the profile is on. Must be one of our Canonical Profile Networks.
num_sourcesInteger (> 0)The number of sources that have contributed to the association of this entity with the Person record.
urlStringThe profile URL.
usernameStringThe profile username.

Example

  "profiles": [
    {
      "network": "linkedin",
      "id": "145991517",
      "url": "linkedin.com/in/seanthorne",
      "username": "seanthorne",
      "first_seen": "2017-06-02",
      "last_seen": "2019-07-18",
      "num_sources": 17
    }
  ]

twitter_url

Description The person's Twitter profile URL based on source agreement.
Data Type String

Example

  "twitter_url": "twitter.com/seanthorne5"

twitter_username

Description The person's Twitter profile username based on source agreement.
Data Type String

Example

  "twitter_username": "seanthorne5"

Work History

certifications

Description Any certifications the person has.
Data Type Array [Object]

Field Details

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

FieldData TypeDescription
end_dateString (Date)The expiration date of the certification.
nameStringCertification name
organizationStringThe organization awarding the certification.
start_dateString (Date)The date the certification was awarded.

Example

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

experience

Description The person's work experience.
Data Type Array [Object]

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).

Each work experience object contains the following fields:

FieldData TypeDescription
companyObjectThe company where the person worked.
end_dateString (Date)The date the person left the company. If the person is still working for the company, will be null.
first_seenString (Date)The date that this entity was first associated with the Person record.
last_seenString (Date)The date that this entity was last associated with the Person record.
is_primaryBooleanWhether this is the person's current job or not. If true, this experience will be used to populate the job_ fields.
location_namesArray [String]Locations where the person has worked while with this company (if different from the company HQ).
num_sourcesInteger (> 0)The number of sources that have contributed to the association of this entity with the Person record.
start_dateString (Date)The date the person started at the company.
summaryStringUser-inputted summary of their work experience.
titleObjectThe person's job title while at the company.
experience.company

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

FieldSub FieldData TypeDescription
facebook_urlStringThe company's Facebook URL
foundedInteger (> 0)The founding year of the company.
idStringThe company's PDL ID
industryEnum (String)The self-identified industry of the company. Must be one of the Canonical Industries.
linkedin_idStringThe company's LinkedIn ID
linkedin_urlStringThe company's LinkedIn URL
locationObjectThe location of the company's headquarters. See Common Location Fields for detailed field descriptions.
address_line_2String
continentEnum (String)
countryEnum (String)
geoString
localityString
metroEnum (String)
nameString
postal_codeString
regionString
street_addressString
nameStringThe company name, cleaned and standardized.
rawArray [String]Raw company name.
sizeEnum (String)The self-reported company size range. Must be one of our Canonical Company Sizes.
tickerStringThe company ticker. This field will only have a value if the company's type is public.
twitter_urlStringThe company's Twitter URL
typeEnum (String)The company type. Must be one of our Canonical Company Types.
websiteStringThe company's primary website, cleaned and standardized.
experience.title

See the corresponding Current Job fields for more details on the information included and formatting of these fields.

FieldData TypeDescription
levelsArray [Enum (String)]Canonical Job Title Levels.
nameStringThe cleaned job title.
rawArray [String]Raw job title input.
roleEnum (String)One of the Canonical Job Roles.
sub_roleEnum (String)One of the Canonical Job Sub Roles.

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",
        "ticker": null,
        "type": "private",
        "raw": [
          "people data labs"
        ],
      },
      "location_names": ["san francisco, california, united states"],
      "end_date": null,
      "start_date": "2015-03",
      "title": {
        "name": "chief executive officer and co-founder",
        "raw": [
          "co-founder & ceo",
          "co-founder & ceo",
          "co-founder and chief executive officer"
        ],
        "role": "operations",
        "sub_role": "logistics",
        "levels": [
          "cxo",
          "owner"
        ],
      },
      "is_primary": true,
      "summary": "worked on the \"search analytics\" team to understand our users better",
      "first_seen": "2018-10-11",
      "last_seen": "2022-11-15",
      "num_sources": 17
    },
  ]

industry

Description The most relevant industry for this person based on their work history.
Data Type Enum (String)

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"

inferred_years_experience

Description The person's inferred years of total work experience.
Data Type Integer (0 - 100)

Field Details

The value will be between 0 and 100.

Example

  "inferred_years_experience": 7

interests

Description The person's self-reported interests.
Data Type Array [String]

Field Details

Each interest is cleaned (lowercased, stripped of whitespace, etc.). We don't have a canonical list of interests but we remove profanity and do some basic cleaning.

Example

  "interests": [
    "data"
  ]

job_history

Description Additional professional positions that may have been removed or changed on resumes.
Data Type Array [Object]

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.

FieldData TypeDescription
company_idStringPDL Company ID
company_nameStringCompany Name
first_seenString (Date)The date that this experience was first associated with this record.
last_seenString (Date)The date that this experience was last associated with this record.
num_sourcesInteger (> 0)The number of sources that have contributed to the association of this profile with this record.
titleStringJob Title at this company.

Example

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

skills

Description The person's self-reported skills.
Data Type Array [String]

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"
  ]

summary

Description User-inputted personal summary.
Data Type String

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"

PDL Record Information & Metadata

dataset_version

Description The major or minor release number.
Data Type String

Field Details

This field currently exists in Person Enrichment API responses. (Person Search and Person Identify APIs use version_status).

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

Example

  "dataset_version": "19.2"

first_seen

Description The date when this record was first created in our data.
Data Type String (Date)

Example

  "first_seen": "2017-06-02"

num_records

Description The number of unique raw records contributing to this specific PDL profile.
Data Type Integer (> 0)

Example

  "num_records": 420

num_sources

Description The number of unique sources contributing to this specific PDL profile.
Data Type Integer (> 0)

Example

  "num_sources": 72

operation_id

Description An identifier for an operation in a Data License delivery, used for troubleshooting.
Data Type String

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"

version_status

❗️

DEPRECATION NOTICE

This object has been deprecated in API responses.

Description Metadata about the version of the dataset used to retrieve this record.
Data Type Object

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.

FieldData TypeDescription
containsArray [String]The list of IDs that have been merged into this record since the last release.
current_versionStringThe current data version.
previous_versionStringThe previous data version.
statusEnum (String)The changes made to this record between the previous release and the current one. One of our Canonical Version Statuses.

Example

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