Webhook for Person Retrieve API

Receive Person Data updates in a more scalable way

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.

1440

Diagram showing standard flow for using Person Retrieve API without the webhook.

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 the customer has called using the Person Enrich, Search, and Identify APIs 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.
2780

Diagram showing flow for using Retrieve API with the webhook.

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?

The webhook will look for any updates to any PDL IDs the customer has called using the Person Enrichment, Person Search, and Person Identify APIs.

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 customers. It is not available for Data License or self-serve customers at this time.

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