Company Enrichment API

The endpoint for the company enrichment api is https://api.peopledatalabs.com/v5/company/enrich

Company Enrichment API Access and Billing

When a matching company is returned, the HTTP Response code will be 200, and when no matching company is found or returned, the HTTP Response code will be a 404. We charge per match.

Usage

PDL's company enrichment API is designed to provide a one to one company match. The company data provided by this endpoint includes all the fields in our Company Schema. These fields are beyond what we provide as part of our Person Data or in the Cleaner APIs.

Requests

See Authentication and Requests to see possible ways to input requests. We recommend using a JSON object to capture request parameters and will do so in the examples below.

Rate Limiting

The standard rate limit is 10/min for testing purposes and 1000/min for paying customers.

Input Parameters

Data points on the queried company are added as key/value pairs to the query string of a request.

The following parameters can be used to specify information on the requested company. Adding more data points to a request increases the probability of a 200 response and the likelihood score. Adding unique parameters like website, ticker, or profile are more likely to yield a match than a name.

Parameter NameDescriptionExample
nameCompany nameGoogle, Inc.
profileCompany social profile.linkedin.com/company/google
tickerCompany stock ticker.GOOGL
websiteCompany Websitegoogle.com
locationComplete or partial company location. You can input multiple location values.1600 Amphitheatre Pkwy, Mountain View, CA 94043
localityCompany locality. You can only input 1 locality.mountainview
regionCompany region. You can only input 1 region.california
countryCompany country. You can only input 1 country.united states
street_addressCompany locality. You can only input 1 locality.1600 Ampitheatre Pkwy
postal_codeCompany postal code. You can only input 1 postal code.94043

For our Company Enrichment API we require a non-ambiguous match. We require that you input a name OR ticker OR website OR profile.

Response

When an API request is executed, the queried data points are preprocessed and built into a query, which is then executed against our company dataset. Most profiles and websites map to a unique company. Company names are fuzzy matched based on name appearance relative to different unique company profiles. The company name which appears most frequently in our data is the one who is most likely to be the company returned in a 200 HTTP response code. If we do not find a match we will return a 404 HTTP response code. If we cannot resolve to a unique company based on a name we will also return a 404 response.

Abridged Response Example (full example here):

{
    "status": 200,
    "id": "google",
    "name": "google",
     "founded": "1998",
     ...
     }
}

Likelihood Score

What is it?

Every match that the API finds during the enrichment process is assigned a likelihood score, which is an integer between 1 - 10 representing the confidence that the returned profile is the same as the profile requested. A score of 1 represents a very low confidence level, and 10 represents the highest degree of confidence. The likelihood score is logarithmic such that a response which returns a likelihood score of 2 will roughly have just a 10 to 30 percent chance of being the same person as the one requested.

You can use the min_likelihood parameter in your API request to specify a threshold likelihood score you want the response to meet or exceed.

Examples

import requests

url = "https://api.peopledatalabs.com/v5/company/enrich"

querystring = {"website":"google.com"}

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

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl -X GET -G \
  'https://api.peopledatalabs.com/v5/company/enrich'\
  -H 'X-Api-Key: xxxx'\
  --data-urlencode 'website=google.com'
import requests

url = "https://api.peopledatalabs.com/v5/company/enrich"

querystring = {
                "website":"google.com",
                "name": "google"
              }

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

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl -X GET -G \
  'https://api.peopledatalabs.com/v5/company/enrich'\
  -H 'X-Api-Key: xxxx'\
  --data-urlencode 'name=facebook'\
  --data-urlencode 'website=fb.com'

Controlling What Counts As A Successful Response

These parameters can be used to describe the characteristics an API response must possess to return a 200.

Parameter Name     DescriptionDefault
min_likelihoodThe minimum likelihood score a response must have to return a 2002
requiredParameter specifying the fields and data points a response must have to return a 200

For more information on the min_likelihood param, see the likelihood section, and for more information on the required param, see the required param section.

min_likelihood Parameter

This parameter allows you to specify the tradeoff between 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.

Some general rules of thumb for setting this parameter are as follows:

  • For use cases which rely on a high degree of data accuracy, use a value of ≥ 6 for the min_likelihood value
  • Requests made with only a few less-specific data points, e.g. 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

import requests

url = "https://api.peopledatalabs.com/v5/company/enrich"

querystring = {
                            "website":"google.com",
                                "min_likelihood": 5
                            }

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

response = requests.request("GET", url, headers=headers, params=querystring)

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'

Required Parameter

The required parameter ensures that you only get charged for responses which have the data fields you're interested in. You can use any company fields for required parameters except those you use as search parameters/input fields. If you include a field in both the request and the required parameters, the required parameter will not work. The value is formatted as a boolean statements.

Example

import requests

url = "https://api.peopledatalabs.com/v5/company/enrich"

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

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

response = requests.request("GET", url, headers=headers, params=querystring)

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'

Full Response

{
  "status": 200,
  "name": "google",
  "size": "10001+",
  "id": "google",
  "founded": 1998,
  "industry": "internet",
  "location": {
    "name": "mountain view, california, united states",
    "locality": "mountain view",
    "region": "california",
    "metro": "san francisco, california",
    "country": "united states",
    "continent": "north america",
    "street_address": "1600 amphitheatre parkway",
    "address_line_2": null,
    "postal_code": "94043",
    "geo": null
  },
  "linkedin_id": "1441",
  "linkedin_url": "linkedin.com/company/google",
  "facebook_url": "facebook.com/google",
  "twitter_url": "twitter.com/google",
  "profiles": [
    "linkedin.com/company/google",
    "linkedin.com/company/1441",
    "facebook.com/google",
    "twitter.com/google",
    "crunchbase.com/organization/google"
  ],
  "website": "google.com",
  "ticker": "GOOGL",
  "type": "public",
  "summary": "google\u2019s mission is to organize the world\u2018s information and make it universally accessible and useful. since our founding in 1998, google has grown by leaps and bounds. from offering search in a single language we now offer dozens of products and services\u2014including various forms of advertising and web applications for all kinds of tasks\u2014in scores of languages. and starting from two computer science students in a university dorm room, we now have thousands of employees and offices around the world. a lot has changed since the first google search engine appeared. but some things haven\u2019t changed: our dedication to our users and our belief in the possibilities of the internet itself.",
  "tags": [
    "online video",
    "artificial intelligence",
    "mobile",
    "android",
    "cloud",
    "machine learning",
    "virtual reality",
    "apps",
    "software",
    "ads"
  ],
  "headline": null,
  "alternative_names": [
    "google inc.",
    "google, social marketing tools",
    "google, inc.",
    "google inc",
    "google, inc",
    "google summer of code",
    "google maps",
    "google ireland",
    "wildfire, a division of google",
    "wildfire interactive, inc."
  ],
  "alternative_domains": [
    "googlevideo.com",
    "google.nl",
    "google.pt",
    "gkecnapps.cn",
    "youtube.com",
    "youtu.be",
    "youtubeeducation.com",
    "gstatic.cn",
    "youtubekids.com",
    "googleadapis.com"
  ],
  "affiliated_profiles": [
    "youtube",
    "google-cloud",
    "think-with-google",
    "google-ads-",
    "googleworkspace",
    "google-analytics",
    "googlemarketingplatform",
    "google-ad-manager",
    "grow-with-google",
    "google-cloud-partners",
    "google-for-startups",
    "google-small-business",
    "x",
    "google-partners",
    "rework-with-google",
    "googleplaydev",
    "googleadmob",
    "google-user-research.",
    "google-news-initiative",
    "adometry"
  ],
  "likelihood": 4
}```

 

Updated about a month ago


Company Enrichment API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.