Webhook for Person Retrieve API

Overview

The Retrieve API webhook lets you receive person data updates from the Person Retrieve API in a more scalable way.

If you need to keep hundreds of thousands of profiles up-to-date, without the webhook you would have to periodically call the Person Retrieve API hundreds of thousands of times to check every individual record.

We've created a webhook to help automate this process. The webhook functionality works like this:

1. The customer gives PDL their unique URL and any required headers.
2. PDL generates a list of all PDL IDs relevant to the customer* and configures a personalized webhook using that information.
3. When PDL’s data is updated, we cross-reference the list of PDL IDs to check if any of those profiles have been updated.
4. The webhook will send the customer the list of updated PDL IDs to their unique URL.
5. The customer uses the Person Retrieve API to pull the updated record for each ID.

Which IDs are Checked for Updates?

For API Customers, the webhook will check for updates to all IDs the customer has called using the Person Enrichment, Person Search, and Person Identify APIs.

For Data License Customers, the webhook will check for updates to all IDs in the customer's data pull query.

How to Set Up the Webhook

Setting up the webhook is very easy. All you'll need to do is contact your PDL representative and provide:

1. URL: A unique URL where you'd like to receive the webhook updates
2. Headers: Any required headers to make a successful call to the unique URL (such as security or access headers)

Your PDL representative will do the rest!

FAQs

Which PDL IDs will be included in the webhook?

For API Customers, the webhook will check for updates to all IDs the customer has called using the Person Enrichment, Person Search, and Person Identify APIs.

For Data License Customers, the webhook will check for updates to all IDs in the customer's data pull query.

Does the webhook provide real-time updates?

No. The webhook is directly linked to how often we update our data, which is monthly for API customers.

Sample Webhook Response

Once the webhook is activated, any updates to the tracked PDL IDs will trigger a POST message to the customer's unique URL in the format below:

HTTP POST
HEADERS: <headers that were included during webhook creation>
BODY: [<pdl id1>,<pdl id2>,...]

Example:

[
  "qEnOZ5Oh0poWnQ1luFBfVw_0000"
]

For examples of how to use the Person Retrieve API to fetch updated records using PDL IDs, see Examples - Person Retrieve API and Bulk Person Retrieve API.

Access & Billing

The webhook functionality is available for our subscribing enterprise API and Data License customers. It is not available for self-serve customers at this time.

If you’d like access, please reach out to us.