Bulk Person Retrieve API
The endpoint for the Bulk Person Retrieve API is /v5/person/retrieve/bulk
Bulk Endpoint
You can retrieve up to 100 persons in a single HTTP request using the /v5/person/retrieve/bulk endpoint. Retrieves executed against the bulk endpoint must be a POST. The request body of a bulk retrieve request must contain an array called requests, with 1-100 individual request objects, each containing a valid PDL ID. You can find a JSON schema describing the structure of a /v5/person/retrieve/bulk here.
import requests, json
API_KEY = "YOUR API KEY"
pdl_base_url = "https://api.peopledatalabs.com/v5/person/retrieve/bulk"
headers = {
'X-Api-Key': API_KEY,
'Content-Type': 'application/json',
}
body = {
"requests": [
{"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000"},
{"id": "PzFD15NINdBWNULBBkwlig_0000"},
],
"pretty": True,
"titlecase": True,
}
response = requests.post(pdl_base_url, headers=headers, json=body)
print(response.text)
curl -X POST "https://api.peopledatalabs.com/v5/person/retrieve/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
"requests": [
{"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000"},
{"id": "PzFD15NINdBWNULBBkwlig_0000"}
]
}'
Responses are returned as an array of response objects.
[
{"status": 200, "data": ...},
{"status": 200, "data": ...}
]
Tracking Responses
Response objects are always returned in the same order as they were defined in the requests array. However you can also add an object metadata to each request, containing any information specific to that request. If metadata is defined in a request object, it will be returned, unchanged in that request's corresponding response object:
import requests, json
API_KEY = "YOUR API KEY"
pdl_base_url = "https://api.peopledatalabs.com/v5/person/retrieve/bulk"
headers = {
'X-Api-Key': API_KEY,
'Content-Type': 'application/json',
}
body = {
"requests": [
{"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
"metadata": {
"user_id": 123
},
},
{
"id": "PzFD15NINdBWNULBBkwlig_0000",
"metadata": {
"user_id": 569
},
},
],
"pretty": True,
"titlecase": True,
}
response = requests.post(pdl_base_url, headers=headers, json=body)
print(response.text)
curl -X POST "https://api.peopledatalabs.com/v5/person/retrieve/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
"requests": [
{"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
"metadata": {
"user_id": 123
}
},
{
"id": "PzFD15NINdBWNULBBkwlig_0000",
"metadata": {
"user_id": 569
}
}
]
}'
[
{"status": 200, "data": ..., "metadata": {"user_id": "123"}},
{"status": 200, "data": ..., "metadata": {"user_id": "569"}}
]
Any response object in a /v5/person/retrieve/bulk response will either have a status code of 200, 404, or 400. Any valid /v5/person/retrieve/bulk will return with a status code of 200.
The number of remaining retrieve matches in your account will be deducted by the number of 200 responses in a bulk retrieve request as though each request was made individually.
Any malformed, unauthenticated or throttled request will return errors in the same format as documented in the errors section.
import requests, json
API_KEY = "YOUR API KEY"
pdl_base_url = "https://api.peopledatalabs.com/v5/person/retrieve/bulk"
headers = {
'X-Api-Key': API_KEY,
'Content-Type': 'application/json',
}
body = {
"required": "names",
"pretty": True,
"titlecase": True,
}
response = requests.post(pdl_base_url, headers=headers, json=body)
print(response.text)
curl -X POST "https://api.peopledatalabs.com/v5/person/retrieve/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
"required": "names"
}'
{
"status": 400,
"error": {
"type": "invalid_request_error",
"message": "Missing key: 'requests'"
}
}
Bulk Request Limitations
Currently, due to infrastructure constraints, there is a 1MB limit on API responses. Most bulk requests will not hit this limit, however an 80-100 record bulk request that returns rich records may approach or go over this limitation.
There are a few ways to ensure you never run into this limitation:
-
Add the
Accept-Encoding: gzipheader to your request headers. The responses will be gzip compressed and around five times smaller. -
Retrieve less records per call. Enriching around 50 records instead of 100 should bypass this limitation.
Example Response
200 Response Fields
Note that the bulk response is a JSON Array of objects with the following fields:
| Field Name | Type | Description |
|---|---|---|
data | object | The person response object |
status | integer | HTTP Status Code |
billed | boolean | A flag indicating whether the record was charged a credit |
metadata | object | Any metadata that the user included in the request |
Note: metadata is on a per-request basis and generally should be used to connect requests to responses within a call. See this section for more information.
[
{
"status": 200,
"data": {
"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
"full_name": "Sean Thorne",
"first_name": "Sean",
"middle_initial": "F",
"middle_name": "Fong",
"last_initial": "T",
"last_name": "Thorne",
"gender": "Male",
"birth_year": 1990,
"birth_date": null,
"linkedin_url": "linkedin.com/in/seanthorne",
"linkedin_username": "Seanthorne",
"linkedin_id": "145991517",
"facebook_url": "facebook.com/deseanthorne",
"facebook_username": "Deseanthorne",
"facebook_id": "1089351304",
"twitter_url": "twitter.com/seanthorne5",
"twitter_username": "Seanthorne5",
"github_url": null,
"github_username": null,
"work_email": "[email protected]",
"personal_emails": [],
"mobile_phone": "+14155688415",
"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_id": "peopledatalabs",
"job_company_name": "People Data Labs",
"job_company_website": "peopledatalabs.com",
"job_company_size": "11-50",
"job_company_founded": 2015,
"job_company_industry": "Computer Software",
"job_company_linkedin_url": "linkedin.com/company/peopledatalabs",
"job_company_linkedin_id": "18170482",
"job_company_facebook_url": "facebook.com/peopledatalabs",
"job_company_twitter_url": "twitter.com/peopledatalabs",
"job_company_location_name": "San Francisco, California, United States",
"job_company_location_locality": "San Francisco",
"job_company_location_metro": "San Francisco, California",
"job_company_location_region": "California",
"job_company_location_geo": "37.77,-122.41",
"job_company_location_street_address": "455 Market Street",
"job_company_location_address_line_2": "Suite 1670",
"job_company_location_postal_code": "94105",
"job_company_location_country": "United States",
"job_company_location_continent": "North America",
"job_last_updated": "2022-03-09",
"job_start_date": "2015-03",
"location_name": "San Francisco, California, United States",
"location_locality": "San Francisco",
"location_metro": "San Francisco, California",
"location_region": "California",
"location_country": "United States",
"location_continent": "North America",
"location_street_address": null,
"location_address_line_2": null,
"location_postal_code": null,
"location_geo": "37.77,-122.41",
"location_last_updated": "2022-03-09",
"phone_numbers": [
"+14155688415"
],
"emails": [
{
"address": "[email protected]",
"type": null
},
{
"address": "[email protected]",
"type": "professional"
},
{
"address": "[email protected]",
"type": "professional"
},
{
"address": "[email protected]",
"type": "professional"
},
{
"address": "[email protected]",
"type": null
},
{
"address": "[email protected]",
"type": "current_professional"
},
{
"address": "[email protected]",
"type": "current_professional"
},
{
"address": "[email protected]",
"type": "current_professional"
}
],
"interests": [
"Location Based Services",
"Mobile",
"Social Media",
"Colleges",
"University Students",
"Consumer Internet",
"College Campuses"
],
"skills": [
"Entrepreneurship",
"Start Ups",
"Management",
"Public Speaking",
"Strategic Partnerships",
"Strategy",
"Fundraising",
"Saas",
"Enterprise Technology Sales",
"Social Networking"
],
"location_names": [
"San Francisco, California, United States",
"Albany, California, United States",
"Portland, Oregon, United States"
],
"regions": [
"California, United States",
"Oregon, United States"
],
"countries": [
"United States"
],
"street_addresses": [],
"experience": [
{
"company": {
"name": "Hallspot",
"size": "1-10",
"id": "hallspot",
"founded": 2013,
"industry": "Computer Software",
"location": {
"name": "Portland, Oregon, United States",
"locality": "Portland",
"region": "Oregon",
"metro": "Portland, Oregon",
"country": "United States",
"continent": "North America",
"street_address": "1231 Northwest Hoyt Street",
"address_line_2": "Suite 202",
"postal_code": "97209",
"geo": "45.52,-122.67"
},
"linkedin_url": "linkedin.com/company/hallspot",
"linkedin_id": "3019184",
"facebook_url": null,
"twitter_url": "twitter.com/hallspot",
"website": "hallspot.com"
},
"location_names": [],
"end_date": "2015-02",
"start_date": null,
"title": {
"name": "Co-Founder",
"role": null,
"sub_role": null,
"levels": [
"owner"
]
},
"is_primary": false
},
{
"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": [],
"end_date": null,
"start_date": "2015-03",
"title": {
"name": "Co-Founder and Chief Executive Officer",
"role": null,
"sub_role": null,
"levels": [
"owner",
"cxo"
]
},
"is_primary": true
}
],
"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",
"facebook_url": "facebook.com/universityoforegon",
"twitter_url": "twitter.com/uoregon",
"linkedin_id": "19207",
"website": "uoregon.edu",
"domain": "uoregon.edu"
},
"end_date": "2012",
"start_date": "2010",
"gpa": null,
"degrees": [],
"majors": [],
"minors": []
},
{
"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",
"facebook_url": "facebook.com/universityoforegon",
"twitter_url": "twitter.com/uoregon",
"linkedin_id": "19207",
"website": "uoregon.edu",
"domain": "uoregon.edu"
},
"end_date": "2014",
"start_date": "2010",
"gpa": null,
"degrees": [],
"majors": [
"Entrepreneurship"
],
"minors": []
}
],
"profiles": [
{
"network": "linkedin",
"id": "145991517",
"url": "linkedin.com/in/seanthorne",
"username": "seanthorne"
},
{
"network": "facebook",
"id": "1089351304",
"url": "facebook.com/deseanthorne",
"username": "deseanthorne"
},
{
"network": "twitter",
"id": null,
"url": "twitter.com/seanthorne5",
"username": "seanthorne5"
},
{
"network": "gravatar",
"id": null,
"url": "gravatar.com/seanthorne5",
"username": "seanthorne5"
},
{
"network": "klout",
"id": null,
"url": "klout.com/seanthorne5",
"username": "seanthorne5"
},
{
"network": "aboutme",
"id": null,
"url": "about.me/sean_thorne",
"username": "sean_thorne"
},
{
"network": "linkedin",
"id": null,
"url": "linkedin.com/in/sean-thorne-9b9a8540",
"username": "sean-thorne-9b9a8540"
},
{
"network": "angellist",
"id": null,
"url": "angel.co/deseanthorne",
"username": "deseanthorne"
}
],
"version_status": {
"status": "Updated",
"contains": [],
"previous_version": "17.0",
"current_version": "18.0"
}
},
"billed": false,
"metadata": {
"user_id": 123
}
},
{
"status": 200,
"data": {
"id": "PzFD15NINdBWNULBBkwlig_0000",
"full_name": "Hayden Conrad",
"first_name": "Hayden",
"middle_initial": null,
"middle_name": null,
"last_initial": "C",
"last_name": "Conrad",
"gender": null,
"birth_year": null,
"birth_date": null,
"linkedin_url": "linkedin.com/in/haydenconrad",
"linkedin_username": "Haydenconrad",
"linkedin_id": "298065705",
"facebook_url": "facebook.com/hayden.conrad.3",
"facebook_username": "hayden.conrad.3",
"facebook_id": "1283267530",
"twitter_url": null,
"twitter_username": null,
"github_url": null,
"github_username": null,
"work_email": "[email protected]",
"personal_emails": [
"[email protected]"
],
"mobile_phone": "+15038058091",
"industry": "Information Technology and Services",
"job_title": "Director of Data Consulting",
"job_title_role": null,
"job_title_sub_role": null,
"job_title_levels": [
"Director"
],
"job_company_id": "peopledatalabs",
"job_company_name": "People Data Labs",
"job_company_website": "peopledatalabs.com",
"job_company_size": "11-50",
"job_company_founded": 2015,
"job_company_industry": "Computer Software",
"job_company_linkedin_url": "linkedin.com/company/peopledatalabs",
"job_company_linkedin_id": "18170482",
"job_company_facebook_url": "facebook.com/peopledatalabs",
"job_company_twitter_url": "twitter.com/peopledatalabs",
"job_company_location_name": "San Francisco, California, United States",
"job_company_location_locality": "San Francisco",
"job_company_location_metro": "San Francisco, California",
"job_company_location_region": "California",
"job_company_location_geo": "37.77,-122.41",
"job_company_location_street_address": "455 Market Street",
"job_company_location_address_line_2": "Suite 1670",
"job_company_location_postal_code": "94105",
"job_company_location_country": "United States",
"job_company_location_continent": "North America",
"job_last_updated": "2022-03-09",
"job_start_date": "2017-09",
"location_name": "San Francisco, California, United States",
"location_locality": "San Francisco",
"location_metro": "San Francisco, California",
"location_region": "California",
"location_country": "United States",
"location_continent": "North America",
"location_street_address": "1674 Filbert Street",
"location_address_line_2": "Apartment 5",
"location_postal_code": "94123",
"location_geo": "37.77,-122.41",
"location_last_updated": "2022-03-09",
"phone_numbers": [
"+15038058091"
],
"emails": [
{
"address": "[email protected]",
"type": "professional"
},
{
"address": "[email protected]",
"type": "personal"
},
{
"address": "[email protected]",
"type": "current_professional"
}
],
"interests": [
"Investing",
"Consulting",
"Politics",
"Economic Empowerment",
"Education",
"French",
"Finance",
"Jazz Saxophone"
],
"skills": [
"Financial Modeling",
"Corporate Finance",
"Valuation",
"Derivatives",
"Financial Analysis",
"Quantitative Finance",
"Bloomberg",
"Teamwork",
"Analysis",
"Factset",
"Microsoft Excel",
"Finance",
"Public Speaking",
"Investments",
"Research"
],
"location_names": [
"San Francisco, California, United States"
],
"regions": [
"California, United States"
],
"countries": [
"United States"
],
"street_addresses": [
{
"name": "San Francisco, California, United States",
"locality": "San Francisco",
"region": "California",
"metro": "San Francisco, California",
"country": "United States",
"continent": "North America",
"street_address": "1674 Filbert Street",
"address_line_2": "Apartment 5",
"postal_code": "94123",
"geo": "37.77,-122.41"
},
{
"name": "San Francisco, California, United States",
"locality": "San Francisco",
"region": "California",
"metro": "San Francisco, California",
"country": "United States",
"continent": "North America",
"street_address": "2349 Greenwich Street",
"address_line_2": null,
"postal_code": "94123",
"geo": "37.77,-122.41"
}
],
"experience": [
{
"company": {
"name": "Oregon Consulting Group",
"size": "11-50",
"id": "oregonconsultinggroup",
"founded": 2014,
"industry": "Religious Institutions",
"location": {
"name": "Hillsboro, Oregon, United States",
"locality": "Hillsboro",
"region": "Oregon",
"metro": "Portland, Oregon",
"country": "United States",
"continent": "North America",
"street_address": "14989 Southwest Hillsboro Highway",
"address_line_2": null,
"postal_code": "97123",
"geo": "45.52,-122.98"
},
"linkedin_url": "linkedin.com/company/oregonconsultinggroup",
"linkedin_id": "5548012",
"facebook_url": null,
"twitter_url": null,
"website": null
},
"location_names": [
"Eugene, Oregon, United States"
],
"end_date": "2015-06",
"start_date": "2014-01",
"title": {
"name": "President and Co-Founder",
"role": null,
"sub_role": null,
"levels": [
"owner",
"cxo"
]
},
"is_primary": false
},
{
"company": {
"name": "Daimler Western Star Trucks",
"size": null,
"id": null,
"founded": null,
"industry": null,
"location": null,
"linkedin_url": null,
"linkedin_id": null,
"facebook_url": null,
"twitter_url": null,
"website": null
},
"location_names": [
"Portland, Oregon, United States"
],
"end_date": "2012-09",
"start_date": "2012-06",
"title": {
"name": "Summer Intern",
"role": null,
"sub_role": null,
"levels": [
"training"
]
},
"is_primary": false
},
{
"company": {
"name": "University of Oregon",
"size": "5001-10000",
"id": "university-of-oregon",
"founded": 1876,
"industry": "Higher Education",
"location": {
"name": "Eugene, Oregon, United States",
"locality": "Eugene",
"region": "Oregon",
"metro": "Eugene, Oregon",
"country": "United States",
"continent": "North America",
"street_address": "1585 East 13th Avenue",
"address_line_2": null,
"postal_code": "97403",
"geo": "44.05,-123.08"
},
"linkedin_url": "linkedin.com/company/university-of-oregon",
"linkedin_id": "5827",
"facebook_url": "facebook.com/universityoforegon",
"twitter_url": "twitter.com/univ_of_oregon",
"website": "uoregon.edu"
},
"location_names": [
"Eugene, Oregon, United States"
],
"end_date": "2015-06",
"start_date": "2013-09",
"title": {
"name": "Senior Analyst",
"role": null,
"sub_role": null,
"levels": [
"senior"
]
},
"is_primary": false
},
{
"company": {
"name": "Pacific Ridge Capital Partners, LLC",
"size": "1-10",
"id": "pacific-ridge-capital-partners-llc",
"founded": 2010,
"industry": "Investment Management",
"location": {
"name": "Lake Oswego, Oregon, United States",
"locality": "Lake Oswego",
"region": "Oregon",
"metro": "Portland, Oregon",
"country": "United States",
"continent": "North America",
"street_address": "4900 Southwest Meadows Road",
"address_line_2": null,
"postal_code": "97035",
"geo": "45.42,-122.67"
},
"linkedin_url": "linkedin.com/company/pacific-ridge-capital-partners-llc",
"linkedin_id": "1040298",
"facebook_url": null,
"twitter_url": null,
"website": "pacridgecap.com"
},
"location_names": [
"Lake Oswego, Oregon, United States"
],
"end_date": "2014-09",
"start_date": "2014-06",
"title": {
"name": "Summer Analyst",
"role": null,
"sub_role": null,
"levels": []
},
"is_primary": false
},
{
"company": {
"name": "Aj Square Inc",
"size": "201-500",
"id": "aj-square-inc",
"founded": 2003,
"industry": "Computer Software",
"location": {
"name": "United States",
"locality": null,
"region": null,
"metro": null,
"country": "United States",
"continent": "North America",
"street_address": null,
"address_line_2": null,
"postal_code": null,
"geo": null
},
"linkedin_url": "linkedin.com/company/aj-square-inc",
"linkedin_id": "266328",
"facebook_url": "facebook.com/ajsquareinc",
"twitter_url": null,
"website": null
},
"location_names": [
"Madurai, Tamil Nadu, India"
],
"end_date": "2011-08",
"start_date": "2011-07",
"title": {
"name": "Intern",
"role": null,
"sub_role": null,
"levels": [
"training"
]
},
"is_primary": false
},
{
"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": "2017-09",
"title": {
"name": "Director of Data Consulting",
"role": null,
"sub_role": null,
"levels": [
"director"
]
},
"is_primary": true
},
{
"company": {
"name": "First Republic Bank",
"size": "1001-5000",
"id": "first-republic-bank",
"founded": 1985,
"industry": "Banking",
"location": {
"name": "San Francisco, California, United States",
"locality": "San Francisco",
"region": "California",
"metro": "San Francisco, California",
"country": "United States",
"continent": "North America",
"street_address": "111 Pine Street",
"address_line_2": null,
"postal_code": "94111",
"geo": "37.77,-122.41"
},
"linkedin_url": "linkedin.com/company/first-republic-bank",
"linkedin_id": "9112",
"facebook_url": "facebook.com/firstrepublicbank",
"twitter_url": "twitter.com/firstrepublic",
"website": "firstrepublic.com"
},
"location_names": [
"San Francisco, California, United States"
],
"end_date": "2017-08",
"start_date": "2015-06",
"title": {
"name": "Business Analyst, Private Wealth Management Technology",
"role": "Finance",
"sub_role": "Investment",
"levels": []
},
"is_primary": false
}
],
"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",
"facebook_url": "facebook.com/universityoforegon",
"twitter_url": "twitter.com/uoregon",
"linkedin_id": "19207",
"website": "uoregon.edu",
"domain": "uoregon.edu"
},
"end_date": "2015",
"start_date": "2011",
"gpa": null,
"degrees": [
"Bachelors",
"Bachelor of Science"
],
"majors": [
"Business Administration",
"Finance"
],
"minors": []
}
],
"profiles": [
{
"network": "linkedin",
"id": "298065705",
"url": "linkedin.com/in/haydenconrad",
"username": "haydenconrad"
},
{
"network": "facebook",
"id": "1283267530",
"url": "facebook.com/hayden.conrad.3",
"username": "hayden.conrad.3"
},
{
"network": "linkedin",
"id": null,
"url": "linkedin.com/in/hayden-conrad-8899a383",
"username": "hayden-conrad-8899a383"
},
{
"network": "quora",
"id": null,
"url": "quora.com/hayden-conrad",
"username": "hayden-conrad"
}
],
"version_status": {
"status": "Updated",
"contains": [],
"previous_version": "17.0",
"current_version": "18.0"
}
},
"billed": false,
"metadata": {
"user_id": 569
}
}
]
Updated 25 days ago
Did this page help you?