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

## Required Parameters

The request must have enough data points to find a clear match. A valid request must include **at least one** of: OR [`pdl_id`](#pdl_id) OR [`name`](#name) OR [`ticker`](#ticker) OR [`website`](#website) OR [`profile`](#profile).

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

### `pdl_id`

| Type     | Description                                                                                                                                                                                                               | Example                                   |
| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------- |
| `String` | The PDL ID or `linkedin_slug` for a record in our Company Dataset. <br /><br />  **Note**: If you enrich using `pdl_id` and anything else, only the `pdl_id` field is used and the other inputs for matching are ignored. | `aKCIYBNF9ey6o5CjHCCO4goHYKlf`or `google` |

### `name`

| Type     | Description         | Example        |
| :------- | :------------------ | :------------- |
| `String` | The company's name. | `Google, Inc.` |

### `profile`

| Type     | Description                   | Example                       |
| :------- | :---------------------------- | :---------------------------- |
| `String` | The company's social profile. | `linkedin.com/company/google` |

### `ticker`

| Type     | Description                                     | Example |
| :------- | :---------------------------------------------- | :------ |
| `String` | The company's stock ticker, if publicly traded. | `GOOGL` |

### `website`

| Type     | Description            | Example      |
| :------- | :--------------------- | :----------- |
| `String` | The company's website. | `google.com` |

### `location`

| Type     | Description                                                                                               | Example                                           |
| :------- | :-------------------------------------------------------------------------------------------------------- | :------------------------------------------------ |
| `String` | The location of the company's headquarters. This can be anything from a street address to a country name. | `1600 Amphitheatre Pkwy, Mountain View, CA 94043` |

You can input multiple location values.

### `street_address `

| Type     | Description                      | Example                  |
| :------- | :------------------------------- | :----------------------- |
| `String` | The company HQ's street address. | `1600 Amphitheatre Pkwy` |

### `locality`

| Type     | Description                | Example         |
| :------- | :------------------------- | :-------------- |
| `String` | The company HQ's locality. | `Mountain View` |

### `region`

| Type     | Description              | Example      |
| :------- | :----------------------- | :----------- |
| `String` | The company HQ's region. | `California` |

### `country`

| Type     | Description               | Example         |
| :------- | :------------------------ | :-------------- |
| `String` | The company HQ's country. | `United States` |

### `postal_code`

| Type     | Description                   | Example |
| :------- | :---------------------------- | :------ |
| `String` | The company HQ's postal code. | `83701` |

### `data_include`

| Type     | Description                                                                                             | Default | Example                 |
| :------- | :------------------------------------------------------------------------------------------------------ | :------ | :---------------------- |
| `String` | A comma-separated string of [company fields](https://docs.peopledatalabs.com/docs/company-schema) that you want the response to include. |         | `"name,location.metro"` |

If this input parameter is not included, the full [company profile](https://docs.peopledatalabs.com/docs/company-schema) will be returned.

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

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, `"-founded,location"` will remove the `founded` and `location` 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`  |

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

### `include_if_matched`

| Type      | Description                                                                                                                       | Default | Example |
| :-------- | :-------------------------------------------------------------------------------------------------------------------------------- | :------ | :------ |
| `Boolean` | If `true`, the response will include the top-level field `matched` that contains a list of every input that matched this profile. | `false` | `true`  |

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

```json
{
   "name": "people data labs",
   "profile": "linkedin.com/company/peopledatalabs",
   "country": "abu dhabi",
   "include_if_matched": true
}
```

The response would contain:

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

### `min_likelihood`

| Type      | Description                                                                                                        | Default | Example |
| :-------- | :----------------------------------------------------------------------------------------------------------------- | :------ | :------ |
| `Integer` | The minimum likelihood score that a profile must have in order for it to count as a match. Will be between `1-10`. | `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 company requested. Adding more data points to your requests will increase the probability of a successful match (high likelihood score and is actually the requested company).

Here are some general rules of thumb for setting this parameter:

* For use cases which rely on a high degree of data accuracy, use a value ≥ `6`.
* Requests made with only a few less-specific data points, such as a name alone, will return lower scores.
* Requests made with just a name return a score between `2` and `5`, based on the quality of the match.

**Example**

```python Python3 SDK
# 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
QUERY_STRING = {
              	"website":"google.com",
              	"min_likelihood": 5
               }

# Pass the parameters object to the Company Enrichment API
response = CLIENT.company.enrichment(**QUERY_STRING)

# Print the API response
print(response.text)
```

```curl
curl -X GET -G \
  'https://api.peopledatalabs.com/v5/company/enrich'\
  -H 'X-Api-Key: xxxx'\
  --data-urlencode 'website=google.com'
  --data-urlencode 'min_likelihood=5'
```

```javascript JavaScript
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

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

// Create a parameters JSON object
const queryString = {
                        "website":"google.com",
                        "min_likelihood": 5
                    }

// Pass the parameters object to the Company Enrichment API
PDLJSClient.company.enrichment(queryString).then((data) => {
    // Print the API response
    console.log(data);
}).catch((error) => {
    console.log(error);
});
```

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

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

# Create a parameters JSON object
QUERY_STRING = {
                "website":"google.com",
                "min_likelihood": 5
               }

# Pass the parameters object to the Company Enrichment API
response = Peopledatalabs::Enrichment.company(params: QUERY_STRING)

# Print the API response
puts response
```

```go
package main

import (
    "fmt"
    "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
    queryString := pdlmodel.CompanyParams{Website: "google.com"}
    
    params := pdlmodel.EnrichCompanyParams{
        CompanyParams: queryString,
        AdditionalParams: pdlmodel.AdditionalParams {
            MinLikelihood: 5,
        },
    }
    
    // Pass the parameters object to the Company Enrichment API
    response, err := client.Company.Enrich(context.Background(), params)
    // Check for successful response
    if err == nil {
        // Print the API response
        fmt.Println(response)
    }  
}
```

```python Python3
import requests

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

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

# Create a parameters JSON object
QUERY_STRING = {
              	"website":"google.com",
              	"min_likelihood": 5
               }

# Set headers
HEADERS = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-api-key': API_KEY
    }

# Pass the parameters object to the Company Enrichment API
response = requests.request("GET", PDL_URL, headers=HEADERS, params=QUERY_STRING)

# Print the API response
print(response.text)
```

### `required`

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

This parameter ensures that we only charge for responses that include the data fields that you're interested in. You can use any top-level [company fields](https://docs.peopledatalabs.com/docs/company-fields) except those that you use as search parameters and input fields. 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 location and a website*:

```curl
required=location AND website
```

*The response must contain a location or website*:

```curl
required=location OR website  
```

*The response must contain a location and either a website or linkedin\_url*:

```curl
required=location AND (website OR linkedin_url)
```

```python Python3 SDK
# 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
QUERY_STRING = {
              	"website":"google.com",
              	"required": "size"
               }

# Pass the parameters object to the Company Enrichment API
response = CLIENT.company.enrichment(**QUERY_STRING)

# Print the API response
print(response.text)
```

```curl
curl -X GET -G \
  'https://api.peopledatalabs.com/v5/company/enrich'\
  -H 'X-Api-Key: xxxx'\
  --data-urlencode 'website=google.com'
  --data-urlencode 'required=size'
```

```javascript JavaScript
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const queryString = {
                        "website":"google.com",
                        "required": "size"
                    }

PDLJSClient.company.enrichment(queryString).then((data) => {
    console.log(data);
}).catch((error) => {
    console.log(error);
});
```

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

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

# Create a parameters JSON object
QUERY_STRING = {
                "website":"google.com",
              	"required": "size"
               }

# Pass the parameters object to the Company Enrichment API
response = Peopledatalabs::Enrichment.company(params: QUERY_STRING)

# Print the API response
puts response
```

```go
package main

import (
    "fmt"
    "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
    queryString := pdlmodel.CompanyParams{Website: "google.com"}
    
    params := pdlmodel.EnrichCompanyParams{
        CompanyParams: queryString,
        AdditionalParams: pdlmodel.AdditionalParams {
            Required: "size",
        },
    }
    
    // Pass the parameters object to the Company Enrichment API
    response, err := client.Company.Enrich(context.Background(), params)
    // Check for successful response
    if err == nil {
        // Print the API response
        fmt.Println(response)
    }  
}
```

```python Python3
import requests

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

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

# Create a parameters JSON object
QUERY_STRING = {
              	"website":"google.com",
              	"required": "size"
               }

HEADERS = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-api-key': API_KEY
    }

response = requests.request("GET", PDL_URL, headers=HEADERS, params=QUERY_STRING)

print(response.text)
```

### `size`

> 🚧 Warning: Enterprise-Only Parameter
>
> The following parameter is only available for Enterprise customers. To enable the `size` parameter, speak with your Data Consultant.

| Type      | Description                                              | Default | Example |
| :-------- | :------------------------------------------------------- | :------ | :------ |
| `Integer` | The maximum number of results to return (between 1-100). | `1`     | `10`    |

If this parameter is included in the request with a value greater than 1, that number of matching results will be returned sorted from highest [likelihood score](https://docs.peopledatalabs.com/docs/output-response-company-enrichment-api#likelihood) to lowest (within the [`min_likelihood`](#min_likelihood) score threshold).

Using this parameter will change the response type to an **array of objects** as shown in the example below.

**NOTE:** Each profile that is returned in the `data` array will cost 1 Company Enrichment credit, so use caution when setting this parameter.

**Example**

```json
{
  "name": "MRI",
  "size": 2
}
```

```json
{
  "status": 200,
  "size": 2,
  "data":  [
    {
      "name": "mri software",
      "display_name": "MRI Software",
      "size": "1001-5000",
      "employee_count": 3710,
      "id": "E33En1BC79vpLcvFkn1N5gDHWOBW",
      "founded": 1971,
      "industry": "information technology and services",
      ...
      "likelihood": 6
    },
    {
      "name": "mri systems",
      "display_name": "mri systems",
      "size": "1001-5000",
      "employee_count": 3710,
      "id": "E33En1BC79vpLcvFkn1N5gDHWOBW",
      "founded": 1971,
      "industry": "information technology and services",
      ...
      "likelihood": 4
    }
   ]
}
```