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

# Input Parameters - Person Identify API

## Required Parameters

A valid Person Identify API request must include **at least one** of the following:

* [`profile`](#profile)
* [`email`](#email)
* [`phone`](#phone)
* [`email_hash`](#email_hash)
* [`lid`](#lid)
* [`street_address`](#street_address)
* [`locality`](#locality)
* [`region`](#region)
* [`company`](#company)
* [`school`](#school)
* [`location`](#location)
* [`postal_code`](#postal_code)
* [`name`](#name)
* [`first_name`](#first_name) AND [`last_name`](#last_name)

<br />

### `api_key`

| Type     | Description          | Default | Example |
| :------- | :------------------- | :------ | :------ |
| `String` | Your secret API key. |         |         |

Your API Key **must** be included in either the request header or the `api_key` parameter. For more information about request authentication, see the [Authentication](https://docs.peopledatalabs.com/docs/authentication) page.

***

## Optional Parameters

### `name`

| Type     | Description                                          | Example               |
| :------- | :--------------------------------------------------- | :-------------------- |
| `String` | The person's full name, at least the first and last. | `Jennifer C. Jackson` |

<br />

### `first_name`

| Type     | Description              | Example    |
| :------- | :----------------------- | :--------- |
| `String` | The person's first name. | `Jennifer` |

<br />

### `last_name`

| Type     | Description             | Example   |
| :------- | :---------------------- | :-------- |
| `String` | The person's last name. | `Jackson` |

<br />

### `middle_name`

| Type     | Description               | Example     |
| :------- | :------------------------ | :---------- |
| `String` | The person's middle name. | `Cassandra` |

<br />

### `location`

| Type     | Description                                                                                      | Example           |
| :------- | :----------------------------------------------------------------------------------------------- | :---------------- |
| `String` | The location where a person lives. This can be anything from a street address to a country name. | `Medford, OR USA` |

<br />

### `street_address`

| Type     | Description                                | Example            |
| :------- | :----------------------------------------- | :----------------- |
| `String` | The street address where the person lives. | `1234 Main Street` |

<br />

### `locality`

| Type     | Description                          | Example |
| :------- | :----------------------------------- | :------ |
| `String` | The locality where the person lives. | `Boise` |

<br />

### `region`

| Type     | Description                                 | Example |
| :------- | :------------------------------------------ | :------ |
| `String` | The state or region where the person lives. | `Idaho` |

<br />

### `country`

| Type     | Description                         | Example         |
| :------- | :---------------------------------- | :-------------- |
| `String` | The country where the person lives. | `United States` |

<br />

### `postal_code`

| Type     | Description                                                                                                    | Example |
| :------- | :------------------------------------------------------------------------------------------------------------- | :------ |
| `String` | The postal code where the person lives. If there is no value for country, the postal code is assumed to be US. | `83701` |

<br />

### `company`

| Type     | Description                                                                | Example  |
| :------- | :------------------------------------------------------------------------- | :------- |
| `String` | The name, website, or social URL of a company where the person has worked. | `Amazon` |

<br />

### `school`

| Type     | Description                                                                          | Example              |
| :------- | :----------------------------------------------------------------------------------- | :------------------- |
| `String` | The name, website, or social URL of a university or college the person has attended. | `University of Iowa` |

<br />

### `phone`

| Type     | Description                                                                                                 | Example           |
| :------- | :---------------------------------------------------------------------------------------------------------- | :---------------- |
| `String` | A phone number the person has used. **Input must begin with `+[country code]` for a match to be returned.** | `+1 555-234-1234` |

<br />

### `email`

| Type     | Description                   | Example                         |
| :------- | :---------------------------- | :------------------------------ |
| `String` | An email the person has used. | `renee.c.paulsen1959@yahoo.com` |

<br />

### `email_hash`

| Type     | Description                                                     | Example                                                            |
| :------- | :-------------------------------------------------------------- | :----------------------------------------------------------------- |
| `String` | The SHA-256 or MD5 email hash for an email the person has used. | `e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4` |

<br />

### `profile`

| Type     | Description                                                                                                                                | Example                              |
| :------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------- |
| `String` | A social profile that the person has used (see [list of supported social profiles](https://docs.peopledatalabs.com/docs/social-networks)). | `https://linkedin.com/in/seanthorne` |

<br />

### `lid`

| Type     | Description               | Example     |
| :------- | :------------------------ | :---------- |
| `String` | The person's LinkedIn ID. | `145991517` |

<br />

### `birth_date`

| Type     | Description                                                                               | Example      |
| :------- | :---------------------------------------------------------------------------------------- | :----------- |
| `String` | The person's birth date: either the year or a full birth date in the format `YYYY-MM-DD`. | `1996-10-01` |

<br />

### `pretty`

| Type      | Description                                                                               | Default | Example |
| :-------- | :---------------------------------------------------------------------------------------- | :------ | :------ |
| `Boolean` | Whether the output should have [human-readable](http://jsonprettyprint.net/) indentation. | `false` | `true`  |

<br />

### `titlecase`

| Type      | Description                                                                                                                    | Default | Example |
| :-------- | :----------------------------------------------------------------------------------------------------------------------------- | :------ | :------ |
| `Boolean` | All text in API responses returns as lowercase by default. Setting `titlecase` to `true` will titlecase response data instead. | `false` | `true`  |

### `data_include`

| Type     | Description                                                               | Default | Example                      |
| :------- | :------------------------------------------------------------------------ | :------ | :--------------------------- |
| `String` | A comma-separated string of fields that you want the response to include. |         | `"full_name,emails.address"` |

### `include_if_matched`

| Type      | Description                                                                                                                                                                                           | Default | Example |
| :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :------ |
| `Boolean` | If `true`, the response will include the field [`matches.matched_on`](https://docs.peopledatalabs.com/docs/output-response-person-identify-api#matchesmatched_on) that contains a list of every query input that matched this profile. | `false` | `true`  |

As an example, if we wanted to enrich Sean Thorne using the following query:

```json
{
   "first_name": "sean",
   "last_name": "thorne",
   "company": "people data labs",
   "location": "abu dhabi",
   "include_if_matched": true
}
```

Since Sean's location is in California and not Abu Dhabi in the dataset, the response would contain:

```json
{
   "matched": [
        "company",
        "name"
    ]
}
```