DocumentationAPI Explorer ToolAPI DashboardAPI StatusRoadmapSupport
Documentation
Start Building
Start typing to search…

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

Person Retrieve API Access and Billing

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). A record is considered "updated" when new information is added, existing information is changed, or we have merged a new data source into it. An updated record 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 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.

Updated 14 days ago