FAQs - 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 and 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 that all our Person APIs support. Because of this, any person profile that a PDL API endpoint returns, such as from the Person Enrichment API, the Bulk Person Enrichment API, the Person Search API or the Person Identify API (as well as from our Data License flat files), will contain a PDL ID that you can use with our Person Retrieve API.

📘

Note: Non-Person PDL IDs

Our non-person records, such as those that we include in company and school profiles (for example, from our Cleaner APIs) 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 are a couple of common use cases in which the Person Retrieve API makes sense.

The first (and most common) is refreshing outdated person profiles. If you previously received a person profile and wanted to refresh data from that profile (for example, after a new PDL data release), you could call the Person Retrieve API with the ID from the original record to retrieve the most up-to-date version of this record.

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

What's the difference between the Person Enrichment API and the 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 they 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. It takes this input and standardizes it, and it uses it to rank profiles contained in our Person Dataset. Then it returns the best matching profile as output.

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 that you want and returns the best match from our Person Dataset.
• The Person Retrieve API takes as input a unique identifier for the profile that you want and returns the exact profile requested from our Person Dataset.

For more information, see this section.

How does billing work with the Person Retrieve API?

If you call the Person Retrieve API, we only charge you in the follow scenarios:

1. The ID that you retrieved is one that you had never received in a profile through any of our APIs;
2. The ID that you retrieved is one that you had previously received in a profile through one of our APIs AND we have updated or refreshed the profile since your last call.

Therefore, we will ALWAYS charge data license customers (that is, customers who have never called a PDL API with an ID), for their first call to the Person Retrieve API.