Release NotesDocumentationAPI ReferenceSupportAPI StatusRoadmap
Start Building

Input Parameters - Company Enrichment API

Detailed information on the input parameters for the Company Enrichment API

Suggest Edits

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 OR name OR ticker OR website OR profile.


api_key

TypeDescriptionDefaultExample
StringYour 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 page.

Optional Parameters

pdl_id

📘

Changes in v26.0 (April 2024)

With the April 2024 release, the pdl_id field will now attempt to match inputs against both the id field and linkedin_slug field of a company record. This means you can use either the alphanumeric idor the linkedin_slug as input for the Company Enrichment API.

This change was implemented to maintain backwards compatibility after our change in format to the company ID in our v26.0 release. Please see the April 2024 Release Announcement (v26.0) for more information.

TypeDescriptionExample
StringThe PDL ID or linkedin_slug for a record in our Company Dataset.

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

name

TypeDescriptionExample
StringThe company's name.Google, Inc.

profile

TypeDescriptionExample
StringThe company's social profile.linkedin.com/company/google

ticker

TypeDescriptionExample
StringThe company's stock ticker, if publicly traded.GOOGL

website

TypeDescriptionExample
StringThe company's website.google.com

location

TypeDescriptionExample
StringThe 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

TypeDescriptionExample
StringThe company HQ's street address.1600 Amphitheatre Pkwy

locality

TypeDescriptionExample
StringThe company HQ's locality.Mountain View

region

TypeDescriptionExample
StringThe company HQ's region.California

country

TypeDescriptionExample
StringThe company HQ's country.United States

postal_code

TypeDescriptionExample
StringThe company HQ's postal code.83701

data_include

TypeDescriptionDefaultExample
StringA comma-separated string of company fields that you want the response to include."name,location.metro"

If this input parameter is not included, the full company profile 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

TypeDescriptionDefaultExample
BooleanWhether the output should have human-readable indentation.falsetrue

titlecase

TypeDescriptionDefaultExample
BooleanAll text in API responses returns as lowercase by default. Setting titlecase to true will titlecase response data instead.falsetrue

include_if_matched

TypeDescriptionDefaultExample
BooleanIf true, the response will include the top-level field matched that contains a list of every input that matched this profile.falsetrue

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

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

The response would contain:

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

min_likelihood

TypeDescriptionDefaultExample
IntegerThe minimum likelihood score that a profile must have in order for it to count as a match. Will be between 1-10.26

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

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

// 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);
});

# 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

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)
    }  
}

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

TypeDescriptionDefaultExample
StringThe 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 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:

required=linkedin_url

The response must contain location and a website:

required=location AND website

The response must contain a location or website:

required=location OR website

The response must contain a location and either a website or linkedin_url:

required=location AND (website OR linkedin_url)

# 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 -X GET -G \
  'https://api.peopledatalabs.com/v5/company/enrich'\
  -H 'X-Api-Key: xxxx'\
  --data-urlencode 'website=google.com'
  --data-urlencode 'required=size'

// 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);
});

# 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

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)
    }  
}

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.

TypeDescriptionDefaultExample
IntegerThe maximum number of results to return (between 1-100).110

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 to lowest (within the 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

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

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

Updated 19 days ago