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

# 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>`.

<Info>
  **Note About `<person_id>`**

  When calling the Person Retrieve API in URL, you must include the [PDL Person ID](/docs/archived-input-parameters-person-retrieve-api-archived#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`
</Info>

# 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](/changelog/april-2022-release-notes-v18#retrieve-api-updates), 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

<Info>
  **For More Details, see [Person Retrieve API - Input Parameters](/docs/archived-input-parameters-person-retrieve-api-archived)**

  You can also click on the individual parameter names in the table below to view more information on them.
</Info>

<table>
  <thead>
    <tr>
      <th>
        Parameter Name
      </th>

      <th>
        Required
      </th>

      <th>
        Description
      </th>

      <th>
        Default
      </th>

      <th>
        Example
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        [`person_id`](/docs/archived-input-parameters-person-retrieve-api-archived#person_id)
      </td>

      <td>
        Yes
      </td>

      <td>
        The [PDL Persistent ID](/docs/persistent-ids) 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](#endpoint).
      </td>

      <td>
        None
      </td>

      <td>
        `qEnOZ5Oh0poWnQ1luFBfVw_0000`
      </td>
    </tr>

    <tr>
      <td>
        [`pretty`](/docs/archived-input-parameters-person-retrieve-api-archived#pretty)
      </td>

      <td>
        No
      </td>

      <td>
        Whether the output should have human-readable indentation.
      </td>

      <td>
        `False`
      </td>

      <td>
        `True`
      </td>
    </tr>

    <tr>
      <td>
        [`api_key`](/docs/archived-input-parameters-person-retrieve-api-archived#api_key)
      </td>

      <td>
        No
      </td>

      <td>
        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](/docs/authentication) page.
      </td>

      <td>
        None
      </td>

      <td />
    </tr>
  </tbody>
</table>

# Output Response

## Response Fields

<Info>
  **For More Details, See [Person Retrieve API - Output Response](/docs/archived-output-response-person-retrieve-api-archived).**

  You can also click the field names in the table below to view more information on them.
</Info>

| Field Name                                                                     | Type     | Description                                                                                                                                                                   |
| :----------------------------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`data`](/docs/archived-output-response-person-retrieve-api-archived#data)     | `Object` | The matched profile record, containing fields from our [Person Schema](/docs/fields). Any fields in the profile record that do not contain any data will have a `null` value. |
| [`billed`](/docs/archived-output-response-person-retrieve-api-archived#billed) | `Bool`   | A flag that indicates whether we charged a credit for the record.                                                                                                             |
| [`status`](/docs/archived-output-response-person-retrieve-api-archived#status) | `Int`    | The [API response code](/docs/errors).                                                                                                                                        |

## Response Data Structure

Here is an example response from the Person Retrieve API:

```json JSON theme={null}
{
 "status": 200,
 "data": {
   "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
   "full_name": "sean thorne"
   ...
 },
 "billed": false
}
```

See [Example Person Record](/docs/example-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](/docs/errors).


## Related topics

- [January 2023 Release Notes](/changelog/january-2023-release-notes-v21.md)
- [Reference - Person Enrichment API](/docs/reference-person-enrichment-api.md)
- [Reference - Person Search API](/docs/reference-person-search-api.md)
- [Reference - Person Identify API](/docs/reference-person-identify-api.md)
- [Reference - Person Changelog API](/docs/reference-person-changelog-api.md)