Reference - Person Retrieve API
Reference information for the Person Retrieve API
Endpoint
The endpoint for the Person Retrieve API is v5/person/retrieve/<person_id>.
Note About
<person_id>When calling the Person Retrieve API in URL, you must include the PDL Person ID of the person that you want to look up as part of the endpoint path.
For example, using the ID
qEnOZ5Oh0poWnQ1luFBfVw_0000:
- Correct:
v5/person/retrieve/qEnOZ5Oh0poWnQ1luFBfVw_0000- Incorrect:
v5/person/retrieve?person_id=qEnOZ5Oh0poWnQ1luFBfVw_0000
Billing and Access
This API is in production, and you can access it by using your API key.
We count records that you retrieve from the Person Retrieve API against your Enrichment API credits.
As of the April 2022 (v18) release, we only charge credits for using the Person Retrieve API when returning an updated record, which means a record that we have updated since the last time you accessed it (across any PDL endpoint). We consider a record to be updated when we have merged a new data source into it. It may contain net new information or may indicate that we have verified existing information using updated sources.
Rate Limiting
Our default limit for free customers is 100 per minute. Our default limit for paying customers is 1,000 per minute. Note: this endpoint shares rate limiting with the Person Enrichment API.
Input Parameters
For More Details, see Person Retrieve API - Input Parameters
You can also click on the individual parameter names in the table below to view more information on them.
| Parameter Name | Required | Description | Default | Example |
|---|---|---|---|---|
person_id | Yes | The PDL Persistent ID for a record in our Person Dataset. When calling the Person Retrieve API in URL, you must specify this as part of the endpoint URL. | None | qEnOZ5Oh0poWnQ1luFBfVw_0000 |
pretty | No | Whether the output should have human-readable indentation. | False | True |
api_key | No | Your secret API key. While we do not require this as part of the request parameters, if you do not provide it here, then you must provide it using an alternative means, such as in the headers using the x-api-key field. For more information, see the Authentication page. | None |
Output Response
Response Fields
For More Details, See Person Retrieve API - Output Response.
You can also click the field names in the table below to view more information on them.
| Field Name | Type | Description |
|---|---|---|
data | Object | The matched profile record, containing fields from our Person Schema. Any fields in the profile record that do not contain any data will have a null value. |
billed | Bool | A flag that indicates whether we charged a credit for the record. |
status | Int | The API response code. |
Response Data Structure
Here is an example response from the Person Retrieve API:
{
"status": 200,
"data": {
"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
"full_name": "sean thorne"
...
},
"billed": false
}
See Example Person Record for a full example of the fields included in the data object.
Errors
If the request encounters an error, it will instead return an Error Response in the format described in Errors.
Updated about 1 month ago