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

```
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](https://docs.peopledatalabs.com/docs/authentication) page.

***

## Optional Request Parameters

### `pdl_id`

| Type     | Description                                                                                                                                                                                                                                    | Example                       |
| :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- |
| `String` | The [PDL Persistent ID](https://docs.peopledatalabs.com/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](https://docs.peopledatalabs.com/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](https://docs.peopledatalabs.com/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`](https://docs.peopledatalabs.com/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
{
   "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"
    ]
}
```

### `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](https://docs.peopledatalabs.com/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*:

```curl
required=linkedin_url
```

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

```curl
required=experience AND work_email
```

*The response must contain experience or emails*:

```curl
required=experience OR emails  
```

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

```curl
required=education AND (emails OR phone_numbers)
```

```python Python3 SDK
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)
```

```curl
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
// 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
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
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
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)
```

**Valid Required Parameters**

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

<Callout icon="⚠️" theme="warn">
  You must have access to the appropriate [Person Data Field Bundle](https://docs.peopledatalabs.com/docs/person-data-field-bundles) for any field you provide as a `required` parameter.
</Callout>

<br />

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