> ## 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 Enrichment API

The Person Enrichment API provides a **one-to-one** person match, retrieving up-to-date information on a unique individual.

# Endpoint

The endpoint for the Person Enrichment API is `https://api.peopledatalabs.com/v5/person/enrich`.

# Person Enrichment API Access and Billing

You can access the Person Enrichment API through our [self-signup dashboard](https://peopledatalabs.com/signup/)

When the API finds a matching person, it returns this person along with an HTTP response code of `200`. When it doesn't find a matching person, it returns an HTTP response code of `404`. We charge **per match**.

# Requests

See [Authentication](https://docs.peopledatalabs.com/docs/authentication) and [Requests](https://docs.peopledatalabs.com/docs/requests) sections to see all possible ways to input a request. We recommend using a JSON object to capture input parameters and will do so in the examples.

# Rate Limiting

Our default limit for free customers is 100 per minute. Our default limit for paying customers is 1,000 per minute.

**Note**: To allow for more enrichments without putting too much strain on our system, you can use the [Bulk Person Enrichment API](https://docs.peopledatalabs.com/docs/bulk-person-enrichment-api) to increase the number of enrichments per request, effectively increasing your rate limit by up to a hundred times.

# Input Parameters

When querying the API in URL, you can add data points to a queried person as key/value pairs at the end of a `v5` request string.

You can use the following parameters to specify information on a requested person. Adding more data points to a request increases the probability of a `200` response and will further increase the accuracy of the response's [Likelihood Score](https://docs.peopledatalabs.com/docs/output-response-person-enrichment-api#likelihood).

All query parameters listed below are optional.

> 📘 For more details, see [Input Parameters - Person Enrichment API](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api)
>
> You can also click on the individual parameter names in the table below to view more information on them.

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

      <th>
        Description
      </th>

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

  <tbody>
    <tr>
      <td>
        [`pdl_id`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#pdl_id)
      </td>

      <td>
        The [PDL Persistent ID](https://docs.peopledatalabs.com/docs/persistent-ids) for a record in our Person Dataset.

        * \*Note:\*\* If you enrich on ID and anything else, only ID is used and the other inputs for matching are ignored.
      </td>

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

    <tr>
      <td>
        [`name`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#name)
      </td>

      <td>
        The person's full name, at least the first and last.
      </td>

      <td>
        `Jennifer C. Jackson`
      </td>
    </tr>

    <tr>
      <td>
        [`first_name`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#first_name)
      </td>

      <td>
        The person's first name.
      </td>

      <td>
        `Jennifer`
      </td>
    </tr>

    <tr>
      <td>
        [`last_name`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#last_name)
      </td>

      <td>
        The person's last name.
      </td>

      <td>
        `Jackson`
      </td>
    </tr>

    <tr>
      <td>
        [`middle_name`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#middle_name)
      </td>

      <td>
        The person's middle name.
      </td>

      <td>
        `Cassandra`
      </td>
    </tr>

    <tr>
      <td>
        [`location`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#location)
      </td>

      <td>
        The location in which a person lives. This can be anything from a street address to a country name.
      </td>

      <td>
        `Medford, OR USA`
      </td>
    </tr>

    <tr>
      <td>
        [`street_address`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#street_address)
      </td>

      <td>
        The street address at which the person lives.
      </td>

      <td>
        `1234 Main Street`
      </td>
    </tr>

    <tr>
      <td>
        [`locality`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#locality)
      </td>

      <td>
        The locality in which the person lives.
      </td>

      <td>
        `Boise`
      </td>
    </tr>

    <tr>
      <td>
        [`region`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#region)
      </td>

      <td>
        The state or region in which the person lives.
      </td>

      <td>
        `Idaho`
      </td>
    </tr>

    <tr>
      <td>
        [`country`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#country)
      </td>

      <td>
        The country in which the person lives.
      </td>

      <td>
        `United States`
      </td>
    </tr>

    <tr>
      <td>
        [`postal_code`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#postal_code)
      </td>

      <td>
        The postal code in which the person lives. If there is no value for `country`, the postal code is assumed to be in the US.
      </td>

      <td>
        `83701`
      </td>
    </tr>

    <tr>
      <td>
        [`company`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#company)
      </td>

      <td>
        The name, website or social URL of the company where the person has worked.
      </td>

      <td>
        `Amazon Web Services`
      </td>
    </tr>

    <tr>
      <td>
        [`school`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#school)
      </td>

      <td>
        The name, website or social URL of the university or college that the person has attended.
      </td>

      <td>
        `University of Iowa`
      </td>
    </tr>

    <tr>
      <td>
        [`phone`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#phone)
      </td>

      <td>
        A phone number the person has used. \*\*Input must begin with`+[country code]` for a match to be returned. \*\*
      </td>

      <td>
        `+1 555-234-1234`
      </td>
    </tr>

    <tr>
      <td>
        [`email`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#email)
      </td>

      <td>
        The email that the person has used.
      </td>

      <td>
        `renee.c.paulsen1959@yahoo.com`
      </td>
    </tr>

    <tr>
      <td>
        [`email_hash`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#email_hash)
      </td>

      <td>
        The SHA-256 or MD5 email hash.
      </td>

      <td>
        `e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4 `
      </td>
    </tr>

    <tr>
      <td>
        [`profile`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#profile)
      </td>

      <td>
        A social profile that the person has used (see [list of available social profiles](https://docs.peopledatalabs.com/docs/social-networks)).
      </td>

      <td>
        `https://linkedin.com/in/seanthorne`.
      </td>
    </tr>

    <tr>
      <td>
        [`lid`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#lid)
      </td>

      <td>
        The person's LinkedIn ID.
      </td>

      <td>
        `145991517`
      </td>
    </tr>

    <tr>
      <td>
        [`birth_date`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#birth_date)
      </td>

      <td>
        The person's birth date: either the year or a full birth date.
      </td>

      <td>
        `1996-10-01`
      </td>
    </tr>

    <tr>
      <td>
        [`api_key`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#api_key)
      </td>

      <td>
        Your secret API key.<br /> <br />**Note**: You can also provide this in the request header instead, as shown on the [Authentication](https://docs.peopledatalabs.com/docs/authentication) page.
      </td>

      <td />
    </tr>
  </tbody>
</Table>

## Additional Input Parameters

You are not required to use the following additional input parameters. They generally transform or control various aspects of the enrichment process (returning matches or formatting results.)

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

      <th>
        Description
      </th>

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

  <tbody>
    <tr>
      <td>
        [`titlecase`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#titlecase)
      </td>

      <td>
        All text in the API responses returns as lowercase by default. Setting `titlecase` to `true` will titlecase the data in `200` responses.
      </td>

      <td>
        `false`
      </td>
    </tr>

    <tr>
      <td>
        [`pretty`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#pretty)
      </td>

      <td>
        Whether the output should have [human-readable](http://jsonprettyprint.net/) indentation.
      </td>

      <td>
        `true`
      </td>
    </tr>

    <tr>
      <td>
        [`min_likelihood`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#min_likelihood)
      </td>

      <td>
        The minimum `likelihood` score that a response must have to return a `200` status code.
      </td>

      <td>
        `2`
      </td>
    </tr>

    <tr>
      <td>
        [`include_if_matched`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#include_if_matched)
      </td>

      <td>
        If set to `true`, the response will include a top-level field called [`matched`](https://docs.peopledatalabs.com/docs/output-response-person-enrichment-api#matched) (along with `data`, `status` and so forth), containing a value for each queried field parameter that was "matched" during our internal query.
      </td>

      <td>
        `false`
      </td>
    </tr>

    <tr>
      <td>
        [`required`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#required)
      </td>

      <td>
        The fields and data points that a response must have to return a `200` status code.
      </td>

      <td>
        `"education AND (emails OR phone_numbers)"`
      </td>
    </tr>

    <tr>
      <td>
        [`data_include`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#data_include)
      </td>

      <td>
        A comma-separated string of the fields that you want the response to include.

        Begin the string with a `-` if you want to *exclude* the specified fields. If you want to exclude all data from being returned, use `data_include=""`.
      </td>

      <td>
        `"full_name,emails.address"`
      </td>
    </tr>
  </tbody>
</Table>

## Minimum Inputs

The minimum combination of data points that a request must contain in order to return a `200` response are:

```curl
profile OR email OR phone OR email_hash OR lid OR ( 
    (
        (first_name AND last_name) OR name) AND 
        (locality OR region OR company OR school OR location OR postal_code)
    )
```

# Output Response

When you execute an API request, we preprocess the queried data points and build them into a query, which we then execute against our [API dataset](https://docs.peopledatalabs.com/docs/datasets#api-dataset). If the query yields one or more matching persons from the dataset, we return in the API response the person who is most likely the person requested, along with a `200` HTTP response code. If we do not find a match, we return a `404` HTTP response code.

## Response Fields

> 📘 For more details, see [Output Response - Person Enrichment API](https://docs.peopledatalabs.com/docs/output-response-person-enrichment-api)
>
> You can also click the field names in the table below to view more information on them.

| Field                                                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                            | Type      |
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| [`data`](https://docs.peopledatalabs.com/docs/output-response-person-enrichment-api#data)             | A matched profile record that contains fields from our [Person Schema](https://docs.peopledatalabs.com/docs/fields). Any fields in the profile record that do not contain any data will have a `null` value.                                                                                                                                                                                                                                                            | `Object`  |
| [`status`](https://docs.peopledatalabs.com/docs/output-response-person-enrichment-api#status)         | The response code. See a description of our [error codes](errors).                                                                                                                                                                                                                                                                                                                                                                     | `Integer` |
| [`likelihood`](https://docs.peopledatalabs.com/docs/output-response-person-enrichment-api#likelihood) | The degree of confidence. The field is an integer between `1` and `10` and represents how confident we are that the person we returned is the same as the person you requested. You can control the minimum likelihood score a response must have in order to return a `200` by using the [`min_likelihood`](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api#min_likelihood) parameter in the API request. | `Integer` |

## Response Data Structure

Here is an example response from the Person Enrichment API:

```json
{
    "status": 200,
    "likelihood": 10,
    "data":  {
            "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
            "full_name": "sean thorne",
            ...
     }
}
```

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