Reference - Company Enrichment API
Reference information for the Company Enrichment API
The Company Enrichment API provides a one-to-one company match. The company data provided by this endpoint includes all the fields in our Company Schema.
Endpoint
The endpoint for the Company Enrichment API is https://api.peopledatalabs.com/v5/company/enrich.
Company Enrichment API Access and Billing
When the API finds a matching company, it returns this company along with an HTTP response code of 200. When it doesn't find a matching company, it returns an HTTP response code of 404. We charge per match.
Requests
See Authentication and Requests for how to input requests. We recommend using a JSON object to capture request parameters and will do so in the examples.
Rate Limiting
The standard rate limit is 10 per minute for free customers and 1,000 per minute for paying customers.
Input Parameters
When querying the API in URL, you can add data points to a queried company as key/value pairs at the end of a v5 request string.
You can use the following parameters to specify information about the requested company. Adding more data points to a request increases the probability of a 200 response and increases the likelihood score. Adding unique parameters such as website, ticker or profile are more likely to yield a match than a name.
For More Details, See Input Parameters - Company Enrichment API
You can also click on the individual parameter names in the table below to view more information on them.
| Parameter Name | Description | Example |
|---|---|---|
pdl_id | The PDL ID for a record in our Company Dataset. Note: If you enrich on ID and anything else, only ID is used and the other inputs for matching are ignored. | google |
name | The company's name. | Google, Inc. |
profile | The company's social profile. | linkedin.com/company/google |
ticker | The company's stock ticker, if publicly traded. | GOOGL |
website | The company's website. | google.com |
location | The complete or partial company location. You can input multiple location values. | 1600 Amphitheatre Pkwy, Mountain View, CA 94043 |
locality | The company's locality. You can only input one locality. | mountainview |
region | The company's region. You can only input one region. | california |
country | The company's country. You can only input one country. | united states |
street_address | The company's street address. You can only input one street address. | 1600 Amphitheatre Pkwy |
postal_code | The company's postal code. You can only input one postal code. | 94043 |
api_key | Your secret API key. Note: You can also provide this in the request header instead, as shown on the Authentication page. |
For our Company Enrichment API, we require a non-ambiguous match. This means that you must input a name OR ticker OR website OR profile.
Additional Input Parameters
You are not required to use the following additional input parameters. They generally transform or control various aspects of the enrichment process (returning matches or formatting results.)
| Parameter Name | Description | Default | Example |
|---|---|---|---|
titlecase | All text in API responses returns as lowercase by default. Setting titlecase to true will titlecase the person data in 200 responses. | false | true |
pretty | Whether the output should have human-readable indentation. | false | true |
include_if_matched | If true, the response includes the top-level field matched (along with data, status and so forth), which includes a value for each queried field parameter that was matched during our internal query. | false | true |
min_likelihood | The minimum likelihood score that a response must have to return a 200. | 2 | 6 |
required | The fields a response must have to return a 200. | ticker | |
data_include | A comma-separated string of fields that you want the response to include. Begin the string with a - if you want to exclude the specified fields. If you want to exclude all data from being returned, use data_include="". | "full_name,emails.address" |
Output Response
When you execute an API request, we preprocess the queried data points and build them into a query, which we then execute against our Company Dataset. Most profiles and websites map to a unique company. We fuzzy-match company names based on name appearance relative to different unique company profiles. The company name that appears most frequently in our data is the one that is most likely to be the company returned in a 200 HTTP response code. If we do not find a match or cannot resolve the query to a unique company based on a name, we will return a 404 HTTP response code.
Response Fields
For More Details, See Output Response - Company Enrichment API
You can also click the field names in the table below to view more information on them.
| Field | Description | Type |
|---|---|---|
status | The response code (see a description of our error codes). | Integer |
likelihood | The degree of confidence. The field is an integer between 1 and 10 that represents how confident we are that the company that we returned is the same as the company that you requested. You can control the minimum likelihood score a response must have in order to return a 200 by using the min_likelihood parameter in the API request. | Integer |
* | The matched profile record containing fields from our Company Schema. Any fields in the profile record that do not contain any data will have a null value. |
Response Data Structure
Here is an example response from the Company Enrichment API:
{
"status": 200,
"name": "people data labs",
"id": "peopledatalabs",
...,
"likelihood": 6
}
See Example Company Record for a full example of the fields included in the response object.
Errors
If the request encounters an error, it will instead return an Error Response in the format described in Errors.
Updated 4 months ago