> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peopledatalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/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](/docs/person-retrieve-api) hundreds of thousands of times to check every individual record.

<Frame caption="Diagram showing standard flow for using Person Retrieve API without the webhook.">
  <img src="https://mintcdn.com/peopledatalabs/YteP5zgY1fC23mEV/images/docs/38f0e3c-Retrieve_Webhook_-_Standard_Flow.svg?fit=max&auto=format&n=YteP5zgY1fC23mEV&q=85&s=55c7d709bb9267caf030d72542875d2b" align="center" data-transcend-suppress width="1440" height="540" data-path="images/docs/38f0e3c-Retrieve_Webhook_-_Standard_Flow.svg" />
</Frame>

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

1. The customer gives PDL their unique URL, any required headers, and any desired input parameters (such as [`filter_updated`](/docs/input-parameters-person-retrieve-api#filter_updated)).
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 and any applicable [filters](/docs/input-parameters-person-retrieve-api#filter_updated) 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](/docs/person-retrieve-api) to pull the updated record for each ID.

<Frame caption="Diagram showing flow for using Retrieve API with the webhook.">
  <img src="https://mintcdn.com/peopledatalabs/YteP5zgY1fC23mEV/images/docs/aa4389b-Retrieve_Webhook_-_Webhook_Flow-2.svg?fit=max&auto=format&n=YteP5zgY1fC23mEV&q=85&s=4f182782751c6e1dc5a65d1fd71333fe" align="center" data-transcend-suppress width="2780" height="720" data-path="images/docs/aa4389b-Retrieve_Webhook_-_Webhook_Flow-2.svg" />
</Frame>

## 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)
3. **Update Filters (Optional):** Any supported [`filter_updated`](/docs/input-parameters-person-retrieve-api#filter_updated) values to determine which record changes will count as an update

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.

**Can I customize which type of changes count as an update?**

Yes! Both API and Data License customers can ask PDL to use the [`filter_updated`](/docs/input-parameters-person-retrieve-api#filter_updated) parameter when setting up your webhook so that only changes to the specific field(s) the filter watches count as updates. You can also use [multiple filters](/docs/input-parameters-person-retrieve-api#using-multiple-filters) with a logical OR operator. However, we do **not** support any customization beyond using `filter_updated` at this time.

## 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:

```text theme={null}
HTTP POST
HEADERS: <headers that were included during webhook creation>
BODY: [<pdl id1>,<pdl id2>,...]
```

Example:

```json JSON theme={null}
[
  "qEnOZ5Oh0poWnQ1luFBfVw_0000",
  "AB4fZ5Oh0poWnQ1luFBfVw_0000",
  "gdD11OZOh0ponQ1luFBfVw_0000"
]
```

For examples of how to use the Person Retrieve API to fetch updated records using PDL IDs, see [Examples - Person Retrieve API](/docs/archived-examples-person-retrieve-api-archived) and [Bulk Person Retrieve API](/docs/archived-bulk-person-retrieve-archived).

## 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](https://www.peopledatalabs.com/talk-to-sales).


## Related topics

- [January 2023 Release Notes](/changelog/january-2023-release-notes-v21.md)
- [July 2023 Release Notes](/changelog/july-2023-release-notes-v23.md)
- [April 2022 Release Notes](/changelog/april-2022-release-notes-v18.md)
- [October 2022 Release Notes](/changelog/october-2022-release-notes-v20.md)
- [Webhooks](/docs/webhooks.md)