FAQs - Person Retrieve API

Miscellaneous (but useful) information on the Person Retrieve API


Have a question you want answered? Ask us!

You can either use the Suggest Edits button in the top right hand corner of this page to ask a question or you can post your question in our Roadmap Board.

What are PDL IDs? Where do I get them from?

Every record in our Person dataset contains a field labeled id (see Person Schema). This id is the PDL ID supported by the Person Retrieve API. Because of this, any person profile returned by a PDL API endpoint (such as the Person Enrichment API, Bulk Person Enrichment API, Person Search API and our Data License flat files will contain a PDL ID that you can use with our Person Retrieve API.


Note: Non-Person PDL IDs

You might be aware that other types of records such as Company profiles and School profiles (such as from our School Cleaner API) also contain id fields. However, these IDs do not refer to person profiles and as a result using a non-person PDL ID with the Person Retrieve API will produce a 404 (not_found) error.

Why would I want to use the Person Retrieve API?

There's a couple common use cases where the Person Retrieve API makes sense. The first (and most common) use case will be for refreshing outdated person profiles. If a user had previously received a person profile and wanted to refresh that exact profile (for instance, after a new PDL data release), then they could use the ID from that record with the Person Retrieve API to retrieve the most up-to-date version of that record.

Another common use case would be when you only have the ID but not the whole record. In this case, the Person Retrieve API would let you access a profile you don't currently have (as opposed to refreshing a profile the user already has.)

What's the difference between the Person Enrichment API and Person Retrieve API?

Both these APIs are similar at a high-level: you input some information about a person profile record that you want to look up and both provide a single person profile in response. They differ in terms of the supported inputs and the matching logic used to find a record in our Person Dataset. The Person Enrichment API supports a variety of input parameters, such as names, emails, social profiles, work and education history and more. The Person Enrichment API then takes this input and standardizes it, and it uses it to rank profiles contained in our Person dataset. The best matching profile is then returned as the output of the Person Enrichment API.

In contrast, the Person Retrieve API only requires only a single input parameter: the PDL Person ID, which it uses to look up the profile with that ID. There is no scoring or ranking because the ID is a unique identifier for records in our Person Dataset.

To summarize:

  • The Person Enrichment API takes as input a description of the profile you want and returns the best match from our Person Dataset.
  • The Person Retrieve API takes as input a unique identifier for the profile you want and returns the exact profile requested from our Person Dataset.

Did this page help you?