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 NameRequiredDescriptionDefaultExample
person_idYesThe 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.NoneqEnOZ5Oh0poWnQ1luFBfVw_0000
prettyNoWhether the output should have human-readable indentation.FalseTrue
api_keyNoYour 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 NameTypeDescription
dataObjectThe 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.
billedBoolA flag that indicates whether we charged a credit for the record.
statusIntThe 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.