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

## Request Requirements

The request must have enough data points to find a clear match. A valid request must include at least one of the following groups of optional parameters:

```SQL theme={null}

profile OR email OR phone OR email_hash OR lid OR pdl_id OR ( 
  (
    (first_name AND last_name) OR name) AND 
    (company OR school OR location OR street_address OR locality 
      OR region OR country OR postal_code OR birth_date)
  )
```

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

***

## Optional Request Parameters

### `pdl_id`

| Type     | Description                                                                                                                                                                                                     | Example                       |
| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- |
| `String` | The [PDL Persistent ID](/docs/persistent-ids) for a record in our Person Dataset. <br /><br />  **Note:** If you enrich on ID and anything else, only ID is used and the other inputs for matching are ignored. | `qEnOZ5Oh0poWnQ1luFBfVw_0000` |

### `name`

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

### `first_name`

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

### `last_name`

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

### `middle_name`

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

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

### `street_address`

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

### `locality`

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

### `region`

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

### `country`

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

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

### `company`

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

### `school`

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

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

### `email`

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

### `email_hash`

| Type     | Description                    | Example                                                            |
| :------- | :----------------------------- | :----------------------------------------------------------------- |
| `String` | The SHA-256 or MD5 email hash. | `e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4` |

### `profile`

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

### `lid`

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

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

### `data_include`

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

If this input parameter is not included, the full [person profile](/docs/fields) will be returned.

Include multiple fields by separating each with a comma. Include specific subfields by using dot notation (ex: `emails.address`).

Exclude field(s) by using `-` as the first character. Entering `-` will exclude all of the comma-separated fields following the character and needs to be entered only once. For example, `"-education,mobile_phone"` will remove the `education` and `mobile_phone fields` from the enriched profile response.

To exclude all data from being returned, use `data_include=""`.

### `pretty`

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

### `min_likelihood`

| Type      | Description                                                                          | Default | Example |
| :-------- | :----------------------------------------------------------------------------------- | :------ | :------ |
| `Integer` | The minimum likelihood score that a response must have in order to count as a match. | `2`     | `6`     |

This parameter allows you to balance precision and recall. In other words, using a high `min_likelihood` value will only return very strong matches but at the risk of not returning any match at all if none can be found above the `min_likelihood` threshold. Alternatively, using a low `min_likelihood` value is more likely to give you a match but at the cost of returning a potentially weaker match.

By default, match recall is kept very high, so a response that returns a likelihood score of `2` will have roughly a 10-30% chance of being the person requested. Adding more data points to your requests will increase the probability of a successful match (high likelihood score and is actually the requested person).

Some general rules of thumb for setting this parameter:

* For use cases which rely on a high degree of data accuracy, use a value of `≥` `6`.
* Requests made with only a few less-specific data points will return lower scores.
* Requests made with only a few data points (for example, a name and a location), will rarely return a likelihood score > `4`.
* Requests made with just a name return a score between `2` and `5`, based on the quality of the match.
* Requests made with just an email will rarely return a likelihood score > `6`.

### `include_if_matched`

| Type      | Description                                                                                                                                                                            | Default | Example |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :------ |
| `Boolean` | If `true`, the response will include the top-level field [`matched`](/docs/output-response-person-enrichment-api) 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 JSON theme={null}
{
   "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 JSON theme={null}
{
   "matched": [
        "company",
        "name"
    ]
}
```

### `required`

| Type     | Description                                                   | Default | Example                                   |
| :------- | :------------------------------------------------------------ | :------ | :---------------------------------------- |
| `String` | The fields a response must have in order to count as a match. |         | `education AND (emails OR phone_numbers)` |

This parameter ensures that we only charge you for responses that include the data fields that you're interested in. You can use any top-level [fields](/docs/fields) as required parameters, except those that you use as search parameters, input fields, and fields that are not included in API responses based on your API key. If you include a field in both the request and the `required` parameter, the `required` parameter will not work.

Format the value as a boolean statement.

**Examples**

*The response must contain a Linkedin URL*:

```bash cURL theme={null}
required=linkedin_url
```

*The response must contain experience and a current work email*:

```bash cURL theme={null}
required=experience AND work_email
```

*The response must contain experience or emails*:

```bash cURL theme={null}
required=experience OR emails  
```

*The response must contain education and either emails or phone\_numbers*:

```bash cURL theme={null}
required=education AND (emails OR phone_numbers)
```

<CodeGroup>
  ```python Python3 SDK expandable theme={null}
  import json

  # See https://github.com/peopledatalabs/peopledatalabs-python
  from peopledatalabs import PDLPY

  # Create a client, specifying your API key
  CLIENT = PDLPY(
      api_key="YOUR API KEY",
  )

  # Create a parameters JSON object
  PARAMS = {
      "name": ["Sean Thorne"],    
      "profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"],
      "required": "emails"
  }

  # Pass the parameters object to the Person Enrichment API
  json_response = CLIENT.person.enrichment(**PARAMS).json()

  # Check for successful response
  if json_response["status"] == 200:
    record = json_response['data']

    # Print selected fields
    print(
      record['work_email'],
      record['full_name'],
      record['job_title'],
      record['job_company_name']
    )

    print(f"Successfully enriched profile with PDL data.")

    # Save enrichment data to JSON file
    with open("my_pdl_enrichment.jsonl", "w") as out:
      out.write(json.dumps(record) + "\n")
  else:
    print("Enrichment unsuccessful. See error and try again.")
    print("error:", json_response)
  ```

  ```bash cURL theme={null}
  curl -X GET -G \
    'https://api.peopledatalabs.com/v5/person/enrich' \
    -H 'X-Api-Key: xxxx' \
    --data-urlencode 'name=Sean Thorne' \
    --data-urlencode 'profile=www.twitter.com/seanthorne5' \
    --data-urlencode 'required=emails'
  ```

  ```javascript JavaScript expandable theme={null}
  // See https://github.com/peopledatalabs/peopledatalabs-js
  import PDLJS from 'peopledatalabs';

  import fs from 'fs';

  // Create a client, specifying your API key
  const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

  // Create a parameters JSON object
  const params = {
    name: "Sean Thorne",
    profile: "www.twitter.com/seanthorne5",
    profile: "linkedin.com/in/seanthorne",
    required: "emails"
  }

  // Pass the parameters object to the Person Enrichment API
  PDLJSClient.person.enrichment(params).then((data) => {
      var record = data.data
      
      // Print selected fields
      console.log(
          record["work_email"],
          record["full_name"],
          record["job_title"],
          record["job_company_name"],
          )
          
      console.log("Successfully enriched profile with PDL data.")
      
      // Save enrichment data to JSON file
      fs.writeFile("my_pdl_enrichment.jsonl", Buffer.from(JSON.stringify(record)), (err) => {
          if (err) throw err;
      });
  }).catch((error) => {
    console.log(error);
  });
  ```

  ```ruby Ruby expandable theme={null}
  require 'json'

  # See https://github.com/peopledatalabs/peopledatalabs-ruby
  require 'peopledatalabs'

  # Set your API key
  Peopledatalabs.api_key = 'YOUR API KEY'

  # Create a parameters JSON object
  PARAMS = {
      "name": ["Sean Thorne"],    
      "profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"],
      "required": "emails"
  }

  # Pass the parameters object to the Person Enrichment API
  json_response = Peopledatalabs::Enrichment.person(params: PARAMS)

  # Check for successful response
  if json_response['status'] == 200
      record = json_response['data']
      
      # Print selected fields
      puts \
          "#{record['work_email']} \
           #{record['full_name']} \
           #{record['job_title']} \
           #{record['job_company_name']}"
      
      puts "Successfully enriched profile with PDL data."
      
      # Save enrichment data to JSON file
      File.open("my_pdl_enrichment.jsonl", "w") do |out|
          out.write(JSON.dump(record) + "\n")
      end
  else
      puts "Enrichment unsuccessful. See error and try again."
      puts "error: #{json_response}"
  end
  ```

  ```go Go expandable theme={null}
  package main

  import (
      "fmt"
      "os"
      "encoding/json"
      "context"
  )

  // See https://github.com/peopledatalabs/peopledatalabs-go
  import (
      pdl "github.com/peopledatalabs/peopledatalabs-go"
      pdlmodel "github.com/peopledatalabs/peopledatalabs-go/model"
  )

  func main() {
      // Set your API key
      apiKey := "YOUR API KEY"
      // Set API key as environmental variable
      // apiKey := os.Getenv("API_KEY")

      // Create a client, specifying your API key
      client := pdl.New(apiKey)
      
      // Create a parameters JSON object
      params := pdlmodel.EnrichPersonParams {
          PersonParams: pdlmodel.PersonParams {
              Name: []string{"Sean Thorne"},
              Profile: []string{"www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"},
          },
          AdditionalParams: pdlmodel.AdditionalParams {
              Required: "emails",
          },
      }

      // Pass the parameters object to the Person Enrichment API
      response, err := client.Person.Enrich(context.Background(), params)
      
      // Check for successful response
      if err == nil {
          // Convert the API response to JSON
          jsonResponse, jsonErr := json.Marshal(response.Data)
          if jsonErr == nil {
              var record map[string]interface{}
              json.Unmarshal(jsonResponse, &record)
              // Print selected fields
              fmt.Println(
                         record["work_email"], 
                         record["full_name"], 
                         record["job_title"], 
                         record["job_company_name"])
          
              fmt.Println("Successfully enriched profile with PDL data.")
          
              // Save enrichment data to JSON file
              out, outErr := os.Create("my_pdl_enrichment.jsonl")
              defer out.Close()
              if outErr == nil {
                  out.WriteString(string(jsonResponse) + "\n")
              }
              out.Sync()
          }
     	} else {
          fmt.Println("Enrichment unsuccessful. See error and try again.")
          fmt.Println("error:", err)
      }
  }
  ```

  ```python Python3 expandable theme={null}
  import requests, json

  # Set your API key
  API_KEY = "YOUR API KEY"

  # Set the Person Enrichment API URL
  PDL_URL = "https://api.peopledatalabs.com/v5/person/enrich"

  # Create a parameters JSON object
  PARAMS = {
      "api_key": API_KEY,
      "name": ["Sean Thorne"],    
      "profile": ["www.twitter.com/seanthorne5", "linkedin.com/in/seanthorne"],
      "required": "emails"
  }

  # Pass the parameters object to the Person Enrichment API
  json_response = requests.get(PDL_URL,  params=PARAMS).json()

  # Check for successful response
  if json_response["status"] == 200:
    record = json_response['data']

    # Print selected fields
    print(
      record['work_email'],
      record['full_name'],
      record['job_title'],
      record['job_company_name']
    )

    print(f"Successfully enriched profile with PDL data.")

    # Save enrichment data to JSON file
    with open("my_pdl_enrichment.jsonl", "w") as out:
      out.write(json.dumps(record) + "\n")
  else:
    print("Enrichment unsuccessful. See error and try again.")
    print("error:", json_response)
  ```
</CodeGroup>

**Valid Required Parameters**

You may specify any [top-level fields](/docs/fields) in the `required` parameter such as the fields below:

<Warning>
  You must have access to the appropriate [Person Data Field Bundle](/docs/person-data-field-bundles) for any field you provide as a `required` parameter.
</Warning>

| Field Name                              |
| --------------------------------------- |
| `birth_date`                            |
| `birth_year`                            |
| `certifications`                        |
| `countries`                             |
| `dataset_version`                       |
| `education`                             |
| `emails`                                |
| `experience`                            |
| `facebook_friends`                      |
| `facebook_id`                           |
| `facebook_url`                          |
| `facebook_username`                     |
| `first_name`                            |
| `first_seen`                            |
| `full_name`                             |
| `sex`                                   |
| `github_url`                            |
| `github_username`                       |
| `headline`                              |
| `id`                                    |
| `industry`                              |
| `inferred_salary`                       |
| `inferred_years_experience`             |
| `interests`                             |
| `job_company_12mo_employee_growth_rate` |
| `job_company_employee_count`            |
| `job_company_facebook_url`              |
| `job_company_founded`                   |
| `job_company_id`                        |
| `job_company_industry`                  |
| `job_company_inferred_revenue`          |
| `job_company_linkedin_id`               |
| `job_company_linkedin_url`              |
| `job_company_location_address_line_2`   |
| `job_company_location_continent`        |
| `job_company_location_country`          |
| `job_company_location_geo`              |
| `job_company_location_locality`         |
| `job_company_location_metro`            |
| `job_company_location_name`             |
| `job_company_location_postal_code`      |
| `job_company_location_region`           |
| `job_company_location_street_address`   |
| `job_company_name`                      |
| `job_company_size`                      |
| `job_company_ticker`                    |
| `job_company_total_funding_raised`      |
| `job_company_twitter_url`               |
| `job_company_type`                      |
| `job_company_website`                   |
| `job_history`                           |
| `job_last_changed`                      |
| `job_last_verified`                     |
| `job_onet_broad_occupation`             |
| `job_onet_code`                         |
| `job_onet_major_group`                  |
| `job_onet_minor_group`                  |
| `job_onet_specific_occupation`          |
| `job_onet_specific_occupation_detail`   |
| `job_start_date`                        |
| `job_summary`                           |
| `job_title`                             |
| `job_title_levels`                      |
| `job_title_role`                        |
| `job_title_sub_role`                    |
| `job_title_class`                       |
| `languages`                             |
| `last_initial`                          |
| `last_name`                             |
| `linkedin_connections`                  |
| `linkedin_id`                           |
| `linkedin_url`                          |
| `linkedin_username`                     |
| `location_address_line_2`               |
| `location_continent`                    |
| `location_country`                      |
| `location_geo`                          |
| `location_last_updated`                 |
| `location_locality`                     |
| `location_metro`                        |
| `location_name`                         |
| `location_names`                        |
| `location_postal_code`                  |
| `location_region`                       |
| `location_street_address`               |
| `middle_initial`                        |
| `middle_name`                           |
| `mobile_phone`                          |
| `name_aliases`                          |
| `num_records`                           |
| `num_sources`                           |
| `operation_id`                          |
| `personal_emails`                       |
| `phone_numbers`                         |
| `phones`                                |
| `possible_birth_dates`                  |
| `possible_emails`                       |
| `possible_location_names`               |
| `possible_phones`                       |
| `possible_profiles`                     |
| `possible_street_addresses`             |
| `profiles`                              |
| `recommended_personal_email`            |
| `regions`                               |
| `skills`                                |
| `street_addresses`                      |
| `summary`                               |
| `twitter_url`                           |
| `twitter_username`                      |
| `work_email`                            |

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


## Related topics

- [Preview Enrichment API](/docs/preview-enrichment-api.md)
- [Reference - Person Enrichment API](/docs/reference-person-enrichment-api.md)
- [Bulk Person Enrichment API](/docs/bulk-enrichment-api.md)
- [Input Parameters - IP Enrichment API](/docs/input-parameters-ip-enrichment-api.md)
- [Person Enrichment API](/docs/person-enrichment-api.md)