Reference - Person Retrieve API

Reference information for the Person Retrieve API

Endpoint

The endpoint for the Person Retrieve API is: v5/person/retrieve/<person_id>.

📘

Note about <person_id>

The PDL Person ID for the record you want to look up must be included as part of the endpoint path.

For example, using the ID qEnOZ5Oh0poWnQ1luFBfVw_0000:

  • Correct: v5/person/retrieve/qEnOZ5Oh0poWnQ1luFBfVw_0000
  • Incorrect: v5/person/retrieve?person_id=qEnOZ5Oh0poWnQ1luFBfVw_0000

Billing and Access

This API is currently in production and users can access it using their API key.

Records in the Retrieve API will be counted against Enrichment API credits. Each record returned by this API is 1 enrichment credit.

Rate Limiting

Our default limit for free customers is 100/min. Our default limit for paying customers is 1000/min. Note that this endpoint shares rate limiting with the Person Enrichment API.

Input Parameters

📘

For more details see Person Retrieve API - Input Parameters

You can also click on the individual parameter names in the table below to view more information as well.

Parameter Name

Required

Description

Default

Example

person_id

Yes

The PDL Persistent ID for a record in our Person Dataset. This must be specified as part of the endpoint url.

None

qEnOZ5Oh0poWnQ1luFBfVw_0000

pretty

No

Whether the output should have human-readable indentation.

False

True

api_key

No

Not required as part of the request parameters, but if not provided here, then it must be provided in the headers using the x-api-key field. For more information see the Authentication page.

None

Nice try - don't share your API keys!

Output Response

Response Fields

📘

For more details see Person Retrieve API - Output Response.

You can also click the field names in the table below to view more information as well.

Field Name

Type

Description

data

Object

The matched profile record, containing fields from our Person Schema. Any fields in the profile record that do not contain any data will have a null value.

status

Int

API Response Code

Abridged Response Data Structure

Here is a layout of the structure of what an example response from the Person Retrieve API might look like. (See a full example response in the next section)

{
 "status": 200,
 "data": {
   "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
   "full_name": "sean thorne",
   "first_name": "sean",
   ...
 }
}

Full Example Response

Input Query (click to toggle)
import requests, json

API_KEY = # YOUR API KEY

pdl_base_url = "https://api.peopledatalabs.com/v5/person/retrieve"

person_id = "qEnOZ5Oh0poWnQ1luFBfVw_0000" # The ID for the record we want

params = {
    "api_key": API_KEY,
    "pretty": True
}

url_path = f"{pdl_base_url}/{person_id}"

json_response = requests.get(url_path,  params=params).json()
print(json_response)

Output Response (full):

{
  "status": 200,
  "data": {
    "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
    "full_name": "sean thorne",
    "first_name": "sean",
    "middle_initial": "f",
    "middle_name": "fong",
    "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": [
      "[email protected]"
    ],
    "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_type": "private",
    "job_company_ticker": null,
    "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": "2021-06-01",
    "job_start_date": "2015-03",
    "job_summary": "People Data Labs builds people data. Leverage our dataset of 1.5 billion unique person profiles as your data foundation to build products, enrich person profiles, power predictive modeling/AI, analysis, and more. We build and maintain our data from our powerful Data Union. We work with thousands of data science teams as their engineering focused people data partner. These include enterprises like adidas, eBay, and Acxiom, as well as startups like Madison Logic, Zoho, and Workable. Backed by Founders Fund. I consult with our engineering customers to solve people data building challenges - [email protected]",
    "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": "2021-06-01",
    "linkedin_connections": 9684,
    "inferred_salary": ">250,000",
    "inferred_years_experience": 9,
    "summary": "Interested in solving the hardest problems the enterprise is facing.",
    "phone_numbers": [
      "+14155688415",
      "+18603784097",
      "+15038301033"
    ],
    "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": "personal"
      },
      {
        "address": "[email protected]",
        "type": null
      },
      {
        "address": "[email protected]",
        "type": "current_professional"
      },
      {
        "address": "[email protected]",
        "type": "current_professional"
      },
      {
        "address": "[email protected]",
        "type": "current_professional"
      }
    ],
    "possible_emails": [
      {
        "address": "[email protected]",
        "type": "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",
          "ticker": null,
          "type": "private",
          "raw": [
            "hallspot",
            "hallspot, inc"
          ],
          "fuzzy_match": false
        },
        "location_names": [],
        "end_date": "2015-02",
        "start_date": "2012-08",
        "title": {
          "name": "co-founder",
          "raw": [
            "co-founder"
          ],
          "role": null,
          "sub_role": null,
          "levels": [
            "owner"
          ]
        },
        "is_primary": false,
        "summary": "CRM for bars and restaurants. Expanded to select west coast college campuses. 800k seed. Angel Conference Presentation: https://www.youtube.com/watch?v=7gL7yIVXuzE"
      },
      {
        "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"
          ],
          "fuzzy_match": false
        },
        "location_names": [],
        "end_date": null,
        "start_date": "2015-03",
        "title": {
          "name": "co-founder and chief executive officer",
          "raw": [
            "co-founder &amp; ceo",
            "co-founder & ceo"
          ],
          "role": null,
          "sub_role": null,
          "levels": [
            "owner",
            "cxo"
          ]
        },
        "is_primary": true,
        "summary": "People Data Labs builds people data. Leverage our dataset of 1.5 billion unique person profiles as your data foundation to build products, enrich person profiles, power predictive modeling/AI, analysis, and more. We build and maintain our data from our powerful Data Union. We work with thousands of data science teams as their engineering focused people data partner. These include enterprises like adidas, eBay, and Acxiom, as well as startups like Madison Logic, Zoho, and Workable. Backed by Founders Fund. I consult with our engineering customers to solve people data building challenges - [email protected]"
      }
    ],
    "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",
          "raw": [
            "university of oregon"
          ]
        },
        "end_date": "2014",
        "start_date": "2010",
        "gpa": null,
        "degrees": [],
        "majors": [
          "entrepreneurship"
        ],
        "minors": [],
        "raw": [
          "data analytics & entrepreneurship",
          ", entrepreneurship",
          "entrepreneurship"
        ],
        "summary": "Entrepreneurship at University of Oregon"
      }
    ],
    "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": "linkedin",
        "id": null,
        "url": "linkedin.com/in/sean-thorne-9b9a8540",
        "username": "sean-thorne-9b9a8540"
      },
      {
        "network": "angellist",
        "id": null,
        "url": "angel.co/deseanthorne",
        "username": "deseanthorne"
      },
      {
        "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/acoaaaizp10baq08dng_c7v7ndeffmpgbo1oiqc",
        "username": "acoaaaizp10baq08dng_c7v7ndeffmpgbo1oiqc"
      }
    ],
    "possible_profiles": [
      {
        "network": "angellist",
        "id": null,
        "url": "angel.co/sean-thorne-1",
        "username": "sean-thorne-1"
      },
      {
        "network": "twitter",
        "id": null,
        "url": "twitter.com/talent_iq",
        "username": "talent_iq"
      },
      {
        "network": "klout",
        "id": null,
        "url": "klout.com/hallspot_dev",
        "username": "hallspot_dev"
      },
      {
        "network": "linkedin",
        "id": null,
        "url": "linkedin.com/in/sean-thorne-4b92813b",
        "username": "sean-thorne-4b92813b"
      },
      {
        "network": "twitter",
        "id": null,
        "url": "twitter.com/seanthorne1",
        "username": "seanthorne1"
      }
    ],
    "certifications": [],
    "languages": [],
    "version_status": {
      "status": "updated",
      "contains": [],
      "previous_version": "14.0",
      "current_version": "15.0"
    }
  }
}

Did this page help you?