The Preview Enrichment API from People Data Labs — 1 operation returning a preview of a person match: a small set of identity fields plus booleans indicating which further fields exist on the record, so a caller can test coverage before spending a full enrichment credit.
openapi: 3.0.3
info:
description: People Data Labs API
title: api.peopledatalabs.com Preview Enrichment API
version: '5.0'
servers:
- url: https://api.peopledatalabs.com
tags:
- name: Preview Enrichment
description: 'Preview a person enrichment match: returns identity fields plus booleans indicating which additional
fields exist, without consuming a full enrichment credit.'
paths:
/v5/person/enrich/preview:
get:
tags:
- Preview Enrichment
summary: /person/enrich/preview
description: Enrich a person record on a variety of fields and receive a preview record in return
security:
- APIKeyHeader: []
parameters:
- name: name
in: query
description: The person's full name, at least first and last
schema:
type: string
- name: first_name
in: query
description: The person's first name
schema:
type: string
- name: last_name
in: query
description: The person's last name
schema:
type: string
- name: middle_name
in: query
description: The person's middle name
schema:
type: string
- name: location
in: query
description: A location in which a person lives
schema:
type: string
- name: street_address
in: query
description: A street address in which the person lives
schema:
type: string
- name: locality
in: query
description: A locality in which the person lives
schema:
type: string
- name: region
in: query
description: A state or region in which the person lives
schema:
type: string
- name: country
in: query
description: A country in which the person lives
schema:
type: string
- name: postal_code
in: query
description: The postal code in which the person lives
schema:
type: string
- name: company
in: query
description: A name, website, or social url of a company where the person has worked
schema:
type: string
- name: school
in: query
description: A name, website, or social url of a university or college the person has attended
schema:
type: string
- name: phone
in: query
description: A phone number the person has used
schema:
type: string
- name: email
in: query
description: An email the person has used
schema:
type: string
- name: email_hash
in: query
description: A sha256 email hash
schema:
type: string
- name: profile
in: query
description: A social profile the person has used. https://docs.peopledatalabs.com/docs/social-networks
schema:
type: string
- name: lid
in: query
description: A LinkedIn numerical ID
schema:
type: string
- name: birth_date
in: query
description: The person's birth date. Either the year, or a full birth date
schema:
type: string
- name: min_likelihood
in: query
description: The minimum likelihood score a response must possess in order to return a 200
schema:
type: integer
maximum: 10
minimum: 0
format: int32
default: 0
- name: required
in: query
description: Parameter specifying the fields and data points a response must have to return a 200
schema:
type: string
- name: titlecase
in: query
description: Setting titlecase to true will titlecase the person data in 200 responses.
schema:
type: boolean
default: false
- name: include_if_matched
in: query
description: If set to true, includes a top-level (alongside "data", "status", etc) field "matched" which
includes a value for each queried field parameter that was "matched-on" during our internal query.
schema:
type: boolean
default: false
responses:
'200':
description: Person Found
content:
application/json:
schema:
$ref: '#/components/schemas/PersonPreview'
'400':
description: Request contained either missing or invalid parameters
'401':
description: Request contained a missing or invalid key
'402':
description: You have reached your account maximum (all matches used)
'404':
description: No records were found matching your request
'405':
description: Request method is not allowed on the requested resource
'429':
description: An error occurred due to requests hitting the API too quick
components:
securitySchemes:
APIKeyHeader:
in: header
name: X-API-Key
type: apiKey
schemas:
PersonPreview:
type: object
properties:
id:
type: string
description: PDL persistent ID
full_name:
type: string
description: The first and the last name fields appended with a space
sex:
type: string
description: The person's sex
linkedin_url:
type: string
format: url
description: Main linkedin profile for this record based on source agreement
job_title:
type: string
description: A person's current job title
job_title_role:
type: string
description: A person's current job title derived role
job_title_sub_role:
type: string
description: A person's job title derived subrole. Each subrole maps to a role
job_title_levels:
type: string
description: A person's current job title derived levels
job_company_name:
type: string
description: A person's current company's name
job_company_website:
type: string
description: A person's current company's website
location_name:
type: string
description: The current canonical location of the person
first_name:
type: boolean
description: A boolean representing if PDL's data contains person's first name
middle_initial:
type: boolean
description: A boolean representing if PDL's data contains person's middle initial
middle_name:
type: boolean
description: A boolean representing if PDL's data contains person's middle name
last_initial:
type: boolean
description: A boolean representing if PDL's data contains person's last initial
last_name:
type: boolean
description: A boolean representing if PDL's data contains person's last name
birth_year:
type: boolean
description: A boolean representing if PDL's data contains the approximated birth date associated with
this person profile. If a profile has a birth_date, the birth_data_fuzzy field will match
birth_date:
type: boolean
description: A boolean representing if PDL's data contains birth date associated with this person profile
linkedin_username:
type: boolean
description: A boolean representing if PDL's data contains main linkedin username for this record based
on source agreement
linkedin_id:
type: boolean
description: A boolean representing if PDL's data contains main linkedin profile id for this record based
on source agreement
facebook_url:
type: boolean
description: A boolean representing if PDL's data contains facebook profile URL
facebook_username:
type: boolean
description: A boolean representing if PDL's data contains facebook username
facebook_id:
type: boolean
description: A boolean representing if PDL's data contains persistent facebook id associated with a person's
facebook profile
twitter_url:
type: boolean
description: A boolean representing if PDL's data contains Twitter URL
twitter_username:
type: boolean
description: A boolean representing if PDL's data contains Twitter Username
github_url:
type: boolean
description: A boolean representing if PDL's data contains main github profile for this record based on
source agreement
github_username:
type: boolean
description: A boolean representing if PDL's data contains main github profile username for this record
based on source agreement
work_email:
type: boolean
description: A boolean representing if PDL's data contains current Professional email
personal_emails:
type: boolean
description: A boolean representing if PDL's data contains a list of all emails tagged as type = personal
mobile_phone:
type: boolean
description: A boolean representing if PDL's data contains highly confident direct dial mobile phone associated
with this person
industry:
type: boolean
description: A boolean representing if PDL's data contains the most relevant industry for this record
based primarily on their tagged personal industries and secondarily on the industries of the companies
that they have worked for
job_company_id:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's PDL ID
job_company_size:
type: boolean
enum:
- 1-10
- 11-50
- 51-200
- 201-500
- 501-1000
- 1001-5000
- 5001-10000
- 10001+
description: A boolean representing if PDL's data contains a person's current company's size range
job_company_founded:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's founded date
job_company_industry:
type: boolean
enum:
- accounting
- airlines/aviation
- alternative dispute resolution
- alternative medicine
- animation
- apparel & fashion
- architecture & planning
- arts and crafts
- automotive
- aviation & aerospace
- banking
- biotechnology
- broadcast media
- building materials
- business supplies and equipment
- capital markets
- chemicals
- civic & social organization
- civil engineering
- commercial real estate
- computer & network security
- computer games
- computer hardware
- computer networking
- computer software
- construction
- consumer electronics
- consumer goods
- consumer services
- cosmetics
- dairy
- defense & space
- design
- e-learning
- education management
- electrical/electronic manufacturing
- entertainment
- environmental services
- events services
- executive office
- facilities services
- farming
- financial services
- fine art
- fishery
- food & beverages
- food production
- fund-raising
- furniture
- gambling & casinos
- glass, ceramics & concrete
- government administration
- government relations
- graphic design
- health, wellness and fitness
- higher education
- hospital & health care
- hospitality
- human resources
- import and export
- individual & family services
- industrial automation
- information services
- information technology and services
- insurance
- international affairs
- international trade and development
- internet
- investment banking
- investment management
- judiciary
- law enforcement
- law practice
- legal services
- legislative office
- leisure, travel & tourism
- libraries
- logistics and supply chain
- luxury goods & jewelry
- machinery
- management consulting
- maritime
- market research
- marketing and advertising
- mechanical or industrial engineering
- media production
- medical devices
- medical practice
- mental health care
- military
- mining & metals
- motion pictures and film
- museums and institutions
- music
- nanotechnology
- newspapers
- non-profit organization management
- oil & energy
- online media
- outsourcing/offshoring
- package/freight delivery
- packaging and containers
- paper & forest products
- performing arts
- pharmaceuticals
- philanthropy
- photography
- plastics
- political organization
- primary/secondary education
- printing
- professional training & coaching
- program development
- public policy
- public relations and communications
- public safety
- publishing
- railroad manufacture
- ranching
- real estate
- recreational facilities and services
- religious institutions
- renewables & environment
- research
- restaurants
- retail
- security and investigations
- semiconductors
- shipbuilding
- sporting goods
- sports
- staffing and recruiting
- supermarkets
- telecommunications
- textiles
- think tanks
- tobacco
- translation and localization
- transportation/trucking/railroad
- utilities
- venture capital & private equity
- veterinary
- warehousing
- wholesale
- wine and spirits
- wireless
- writing and editing
description: A boolean representing if PDL's data contains a person's current company's industry
job_company_linkedin_url:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's linkedin url
job_company_linkedin_id:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's linkedin id
job_company_facebook_url:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's facebook url
job_company_twitter_url:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's twitter url
job_company_location_name:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's HQ canonical location
job_company_location_locality:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's HQ locality
job_company_location_metro:
type: boolean
enum:
- abilene, texas
- akron, ohio
- albany, georgia
- albany, new york
- albany, oregon
- albuquerque, new mexico
- alexandria, louisiana
- allentown, pennsylvania
- altoona, pennsylvania
- amarillo, texas
- ames, iowa
- anchorage, alaska
- ann arbor, michigan
- anniston, alabama
- appleton, wisconsin
- asheville, north carolina
- athens, georgia
- atlanta, georgia
- atlantic city, new jersey
- auburn, alabama
- augusta, georgia
- austin, texas
- bakersfield, california
- baltimore, maryland
- bangor, maine
- barnstable town, massachusetts
- baton rouge, louisiana
- battle creek, michigan
- bay city, michigan
- beaumont, texas
- bellingham, washington
- billings, montana
- binghamton, new york
- birmingham, alabama
- bismarck, north dakota
- blacksburg, virginia
- bloomington, illinois
- bloomington, indiana
- boise city, idaho
- boston, massachusetts
- boulder, colorado
- bowling green, kentucky
- bremerton, washington
- bridgeport, connecticut
- brownsville, texas
- buffalo, new york
- burlington, north carolina
- burlington, vermont
- canton, ohio
- cape coral, florida
- cape girardeau, missouri
- carbondale, illinois
- carson city, nevada
- casper, wyoming
- cedar rapids, iowa
- champaign, illinois
- charleston, south carolina
- charleston, west virginia
- charlotte, north carolina
- charlottesville, virginia
- chattanooga, tennessee
- cheyenne, wyoming
- chicago, illinois
- chico, california
- cincinnati, ohio
- clarksville, tennessee
- cleveland, ohio
- cleveland, tennessee
- coeur d'alene, idaho
- college station, texas
- colorado springs, colorado
- columbia, missouri
- columbia, south carolina
- columbus, georgia
- columbus, indiana
- columbus, ohio
- corpus christi, texas
- corvallis, oregon
- crestview, florida
- cumberland, maryland
- dallas, texas
- dalton, georgia
- danville, illinois
- davenport, iowa
- dayton, ohio
- decatur, alabama
- decatur, illinois
- deltona, florida
- denver, colorado
- des moines, iowa
- detroit, michigan
- district of columbia
- dothan, alabama
- dover, delaware
- dubuque, iowa
- duluth, minnesota
- durham, north carolina
- eau claire, wisconsin
- el centro, california
- el paso, texas
- elizabethtown, kentucky
- elkhart, indiana
- elmira, new york
- enid, oklahoma
- erie, pennsylvania
- eugene, oregon
- evansville, indiana
- fairbanks, alaska
- fargo, north dakota
- farmington, new mexico
- fayetteville, arkansas
- fayetteville, north carolina
- flagstaff, arizona
- flint, michigan
- florence, alabama
- florence, south carolina
- fond du lac, wisconsin
- fort collins, colorado
- fort smith, arkansas
- fort wayne, indiana
- fresno, california
- gadsden, alabama
- gainesville, florida
- gainesville, georgia
- goldsboro, north carolina
- grand forks, north dakota
- grand island, nebraska
- grand junction, colorado
- grand rapids, michigan
- grants pass, oregon
- great falls, montana
- greeley, colorado
- green bay, wisconsin
- greensboro, north carolina
- greenville, north carolina
- greenville, south carolina
- gulfport, mississippi
- hagerstown, maryland
- hanford, california
- harrisburg, pennsylvania
- harrisonburg, virginia
- hartford, connecticut
- hattiesburg, mississippi
- hickory, north carolina
- hilton head island, south carolina
- hinesville, georgia
- hot springs, arkansas
- houma, louisiana
- houston, texas
- huntington, west virginia
- huntsville, alabama
- idaho falls, idaho
- indianapolis, indiana
- iowa city, iowa
- ithaca, new york
- jackson, michigan
- jackson, mississippi
- jackson, tennessee
- jacksonville, florida
- jacksonville, north carolina
- janesville, wisconsin
- jefferson city, missouri
- johnson city, tennessee
- johnstown, pennsylvania
- jonesboro, arkansas
- joplin, missouri
- kahului, hawaii
- kalamazoo, michigan
- kankakee, illinois
- kansas city, missouri
- kennewick, washington
- killeen, texas
- kingsport, tennessee
- kingston, new york
- knoxville, tennessee
- kokomo, indiana
- la crosse, wisconsin
- lafayette, indiana
- lafayette, louisiana
- lake charles, louisiana
- lake havasu city, arizona
- lakeland, florida
- lancaster, pennsylvania
- lansing, michigan
- laredo, texas
- las cruces, new mexico
- las vegas, nevada
- lawrence, kansas
- lawton, oklahoma
- lebanon, pennsylvania
- lewiston, idaho
- lewiston, maine
- lexington, kentucky
- lima, ohio
- lincoln, nebraska
- little rock, arkansas
- logan, utah
- longview, texas
- longview, washington
- los angeles, california
- louisville, kentucky
- lubbock, texas
- lynchburg, virginia
- macon, georgia
- madera, california
- madison, wisconsin
- manchester, new hampshire
- manhattan, kansas
- mankato, minnesota
- mansfield, ohio
- mcallen, texas
- medford, oregon
- memphis, tennessee
- merced, california
- miami, florida
- michigan city, indiana
- midland, michigan
- midland, texas
- milwaukee, wisconsin
- minneapolis, minnesota
- missoula, montana
- mobile, alabama
- modesto, california
- monroe, louisiana
- monroe, michigan
- montgomery, alabama
- morgantown, west virginia
- morristown, tennessee
- mount vernon, washington
- muncie, indiana
- muskegon, michigan
- myrtle beach, south carolina
- napa, california
- naples, florida
- nashville, tennessee
- new bern, north carolina
- new haven, connecticut
- new orleans, louisiana
- new york, new york
- north port, florida
- norwich, connecticut
- ocala, florida
- odessa, texas
- ogden, utah
- oklahoma city, oklahoma
- olympia, washington
- omaha, nebraska
- orlando, florida
- oshkosh, wisconsin
- owensboro, kentucky
- oxnard, california
- palm bay, florida
- panama city, florida
- parkersburg, west virginia
- pensacola, florida
- peoria, illinois
- philadelphia, pennsylvania
- phoenix, arizona
- pine bluff, arkansas
- pittsburgh, pennsylvania
- pittsfield, massachusetts
- pocatello, idaho
- port st. lucie, florida
- portland, maine
- portland, oregon
- poughkeepsie, new york
- prescott valley, arizona
- providence, rhode island
- provo, utah
- pueblo, colorado
- punta gorda, florida
- racine, wisconsin
- raleigh, north carolina
- rapid city, south dakota
- reading, pennsylvania
- redding, california
- reno, nevada
- richmond, virginia
- riverside, california
- roanoke, virginia
- rochester, minnesota
- rochester, new york
- rockford, illinois
- rocky mount, north carolina
- rome, georgia
- sacramento, california
- saginaw, michigan
- salem, oregon
- salinas, california
- salisbury, maryland
- salt lake city, utah
- san angelo, texas
- san antonio, texas
- san diego, california
- san francisco, california
- san jose, california
- san luis obispo, california
- santa cruz, california
- santa fe, new mexico
- santa maria, california
- santa rosa, california
- savannah, georgia
- scranton, pennsylvania
- seattle, washington
- sebastian, florida
- sheboygan, wisconsin
- sherman, texas
- shreveport, louisiana
- sierra vista, arizona
- sioux city, iowa
- sioux falls, south dakota
- south bend, indiana
- spartanburg, south carolina
- spokane, washington
- springfield, illinois
- springfield, massachusetts
- springfield, missouri
- springfield, ohio
- st. cloud, minnesota
- st. george, utah
- st. joseph, missouri
- st. louis, missouri
- state college, pennsylvania
- staunton, virginia
- stockton, california
- sumter, south carolina
- syracuse, new york
- tallahassee, florida
- tampa, florida
- terre haute, indiana
- texarkana, texas
- toledo, ohio
- topeka, kansas
- trenton, new jersey
- tucson, arizona
- tulsa, oklahoma
- tuscaloosa, alabama
- twin falls, idaho
- tyler, texas
- urban honolulu, hawaii
- utica, new york
- valdosta, georgia
- vallejo, california
- victoria, texas
- vineland, new jersey
- virginia beach, virginia
- visalia, california
- waco, texas
- walla walla, washington
- warner robins, georgia
- waterloo, iowa
- watertown, new york
- wausau, wisconsin
- weirton, west virginia
- wenatchee, washington
- wheeling, west virginia
- wichita falls, texas
- wichita, kansas
- williamsport, pennsylvania
- wilmington, north carolina
- winchester, virginia
- worcester, massachusetts
- yakima, washington
- york, pennsylvania
- youngstown, ohio
- yuba city, california
- yuma, arizona
description: A boolean representing if PDL's data contains a person's current company's HQ metro area
job_company_location_region:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's HQ region
job_company_location_geo:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's HQ geo
job_company_location_street_address:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's HQ street_address
job_company_location_address_line_2:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's HQ address line
2
job_company_location_postal_code:
type: boolean
description: A boolean representing if PDL's data contains a person's current company's HQ postal code
job_company_location_country:
type: boolean
enum:
- afghanistan
- albania
- algeria
- american samoa
- andorra
- angola
- anguilla
- antigua and barbuda
- argentina
- armenia
- aruba
- australia
- austria
- azerbaijan
- bahamas
- bahrain
- bangladesh
- barbados
- belarus
- belgium
- belize
- benin
- bermuda
- bhutan
- bolivia
- bosnia and herzegovina
- botswana
- bouvet island
- brazil
- british indian ocean territory
- british virgin islands
- brunei
- bulgaria
- burkina faso
- burundi
- cambodia
- cameroon
- canada
- cape verde
- caribbean netherlands
- cayman islands
- central african republic
- chad
- chile
- china
- christmas island
- cocos (keeling) islands
- colombia
- comoros
- cook islands
- costa rica
- croatia
- cuba
- curaçao
- cyprus
- czechia
- côte d'ivoire
- democratic republic of the congo
- denmark
- djibouti
- dominica
- dominican republic
- ecuador
- egypt
- el salvador
- equatorial guinea
- eritrea
- estonia
- eswatini
- ethiopia
- falkland islands
- faroe islands
- fiji
- finland
- france
- french guiana
- french polynesia
- french southern territories
- gabon
- georgia
- germany
- ghana
- gibraltar
- greece
- greenland
- grenada
- guadeloupe
- guam
- guatemala
- guernsey
- guinea
- guinea-bissau
- guyana
- haiti
- heard island and mcdonald islands
- honduras
- hong kong
- hungary
- iceland
- india
- indonesia
- iran
- iraq
- ireland
- isle of man
- israel
- italy
- jamaica
- japan
- jersey
- jordan
- kazakhstan
- kenya
- kiribati
- kosovo
- kuwait
- kyrgyzstan
- laos
- latvia
- lebanon
- lesotho
- liberia
- libya
- liechtenstein
- lithuania
- luxembourg
- macau
- madagascar
- malawi
- malaysia
- maldives
- mali
- malta
- marshall islands
- martinique
- mauritania
- mauritius
- mayotte
- mexico
- micronesia
- moldova
- monaco
- mongolia
- montenegro
- montserrat
- morocco
- mozambique
- myanmar
- namibia
- nauru
- nepal
- netherlands
- new caledonia
- new zealand
- nicaragua
- niger
- nigeria
- niue
- norfolk island
- north korea
- north macedonia
- northern mariana islands
- norway
- oman
- pakistan
- palau
- palestine
- panama
- papua new guinea
- p
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/peopledatalabs/refs/heads/main/openapi/peopledatalabs-preview-enrichment-api-openapi.yml