Reference - Company Search API

Reference information for the Company Search API

The Company Search API is perfect for finding specific segments of companies that you need to power your projects and products. It gives you direct access to our full Company Dataset. There are many degrees of freedom, which allow you to find any kind of company with a single query.

Endpoint

The endpoint for the Company Search API is https://api.peopledatalabs.com/v5/company/search.

Company Search API Access and Billing

The Company Search API is currently in beta and the information in this section as well as API functionality are subject to change.

To access the Company Search API, reach out to us. Please report any issues or feedback to [email protected] and/or to your Data Consultant.

We charge per record retrieved. Each company record in the data array of the response counts as a single credit against your total package.

Requests

See Authentication and Requests to learn how to input requests. We recommend using a JSON object to capture request parameters and will do so in the examples.

Rate Limiting

The current default rate limit is 10 requests per minute.

Input Parameters

πŸ“˜

For More Details, See Input Parameters - Company Search API

You can also click on the individual parameter names in the table below to view more information on them.

Parameter NameDescriptionDefaultExample
queryAn Elasticsearch (v7.7) query. See our underlying Elasticsearch mapping for reference.{"query": {"term": {"name": "people data labs"}}}
sqlAn SQL query of the format: SELECT * FROM company WHERE XXX, where XXX is a standard SQL boolean query involving our company fields. We will ignore any use of column selections or the LIMIT keyword.SELECT * FROM company WHERE name='people data labs'
sizeThe batch size or the maximum number of matched records to return for this query if they exist. Must be between 1 and 100.1100
from[LEGACY] An offset value for paginating between batches, which can be a number between 0 and 9999. We will execute pagination for a maximum of 10,000 records per query. NOTE: YOU CANNOT USE FROM WITH SCROLL_TOKEN IN THE SAME REQUEST.00, 100, 200 ...
scroll_tokenAn offset key for paginating between batches. Unlike the legacy from, you can use this parameter for any number of records. Each Company Search API response returns a scroll_token, which you can use to fetch the next size records.None104$14.278746
titlecaseAll text in API responses returns as lowercase by default. Setting titlecase to true will titlecase the person data in 200 responses.falsetrue
prettyWhether the output should have human-readable indentation.falsetrue
api_keyYour secret API key (Note: you can also provide this in the request header instead, as shown on the Authentication page).

Output Response

We will return an HTTP response code of 200 for any valid request, regardless of whether records were found for your query or not. For that reason, pay close attention to the total value in your response object to understand query success. Each company record in the data array of the response counts as a single credit against your total package. This value has a maximum of one record by default to prevent accidents.

Response Fields

πŸ“˜

For More Details, See Output Response - Company Search API

You can also click the field names in the table below to view more information as well.

FieldDescriptionType
statusThe response code. See a description of our error codes.Integer
errorThe error object.Object
error.typeThe error type.List (String)
error.message]The error message.String
dataThe data returned. See the full example response or the example company record.Object
totalThe number of records matching a given query or sql input.Integer
scroll_tokenThe scroll value, which you can use for further pagination.String

Abridged Response Data Structure

Here is an example response from the Company Search API:

{
    "status": 200,
    "data": [
        {
            "id": "google",
            "name": "google",
            "website": "google.com",
            ...
        },
        ...
    ],
    "total": 6,
    "scroll_token": "13.312621$543927"
}

Full Example Response

Full Output Response (click to expand)
{
  "status": 200,
  "data": [
    {
      "id": "peopledatalabs",
      "website": "peopledatalabs.com",
      "name": "people data labs",
      "founded": 2015,
      "size": "11-50",
      "location": {
        "name": "san francisco, california, united states",
        "locality": "san francisco",
        "region": "california",
        "metro": "san francisco, california",
        "country": "united states",
        "continent": "north america",
        "street_address": "455 market street",
        "address_line_2": "suite 1670",
        "postal_code": "94105",
        "geo": "37.77,-122.41"
      },
      "industry": "computer software",
      "facebook_url": "facebook.com/peopledatalabs",
      "twitter_url": "twitter.com/peopledatalabs",
      "linkedin_url": "linkedin.com/company/peopledatalabs",
      "linkedin_id": "18170482",
      "email_domains": [],
      "ticker": null,
      "type": "private",
      "profiles": [
        "linkedin.com/company/peopledatalabs",
        "linkedin.com/company/18170482",
        "facebook.com/peopledatalabs",
        "twitter.com/peopledatalabs",
        "crunchbase.com/organization/talentiq"
      ],
      "tags": [
        "data",
        "people data",
        "data science",
        "artificial intelligence",
        "data and analytics",
        "machine learning",
        "analytics",
        "database",
        "software",
        "developer apis"
      ],
      "summary": "people data labs builds people data. \n\nuse our dataset of 1.5 billion unique person profiles to build products, enrich person profiles, power predictive modeling/ai, analysis, and more. we work with technical teams as their engineering focused people data partner. \n\nwe work with thousands of data science teams as their engineering focused people data partner. these include enterprises like adidas, ebay, and acxiom, as well as startups like madison logic, zoho, and workable. we are a deeply technical company, and are backed by two leading engineering venture capital firms - founders fund and 8vc.",
      "headline": "Your Single Source of Truth",
      "alternative_names": [],
      "alternative_domains": [],
      "affiliated_profiles": []
    }
  ],
  "scroll_token": "13.312621$5439277"
  "total": 6
}

Full Field Mapping

{
  "_routing": {
    "required": true
  },
  "date_detection": false,
  "properties": {
    "affiliated_profiles": {
      "type": "keyword"
    },
    "all_subsidiaries": {
      "type": "keyword"
    },
    "alternative_domains": {
      "type": "keyword"
    },
    "alternative_names": {
      "type": "keyword",
      "ignore_above": 256,
      "fields": {
        "text": {
          "type": "text"
        }
      }
    },
    "direct_subsidiaries": {
      "type": "keyword"
    },
    "ein": {
      "type": "keyword"
    },
    "email_domains": {
      "type": "keyword"
    },
    "facebook_url": {
      "type": "keyword"
    },
    "founded": {
      "type": "date",
      "format": "yyyy-MM-dd||yyyy-MM||yyyy",
      "ignore_malformed": true
    },
    "gics_sector": {
      "type": "keyword"
    },
    "headline": {
      "type": "text"
    },
    "id": {
      "type": "keyword"
    },
    "immediate_parent": {
      "type": "keyword"
    },
    "industry": {
      "type": "keyword"
    },
    "insights": {
      "dynamic": "false",
      "properties": {
        "employee_churn_rate": {
          "properties": {
            "12_month": {
              "type": "float"
            },
            "24_month": {
              "type": "float"
            },
            "3_month": {
              "type": "float"
            },
            "6_month": {
              "type": "float"
            }
          }
        },
        "employee_count": {
          "type": "long"
        },
        "employee_growth_rate": {
          "properties": {
            "12_month": {
              "type": "float"
            },
            "24_month": {
              "type": "float"
            },
            "3_month": {
              "type": "float"
            },
            "6_month": {
              "type": "float"
            }
          }
        },
        "inferred_revenue": {
          "type": "keyword"
        }
      }
    },
    "legal_name": {
      "type": "keyword"
    },
    "linkedin_id": {
      "type": "keyword"
    },
    "linkedin_url": {
      "type": "keyword"
    },
    "location": {
      "properties": {
        "address_line_2": {
          "type": "keyword"
        },
        "continent": {
          "type": "keyword"
        },
        "country": {
          "type": "keyword"
        },
        "geo": {
          "type": "geo_point",
          "doc_values": false
        },
        "locality": {
          "type": "keyword"
        },
        "metro": {
          "type": "keyword"
        },
        "name": {
          "type": "keyword"
        },
        "postal_code": {
          "type": "keyword"
        },
        "region": {
          "type": "keyword"
        },
        "street_address": {
          "type": "keyword"
        }
      }
    },
    "mic_exchange": {
      "type": "keyword"
    },
    "naics": {
      "properties": {
        "industry_group": {
          "type": "keyword"
        },
        "naics_code": {
          "type": "keyword"
        },
        "naics_industry": {
          "type": "keyword"
        },
        "national_industry": {
          "type": "keyword"
        },
        "sector": {
          "type": "keyword"
        },
        "sub_sector": {
          "type": "keyword"
        }
      }
    },
    "name": {
      "type": "keyword",
      "ignore_above": 256,
      "fields": {
        "text": {
          "type": "text"
        }
      }
    },
    "pdl_id": {
      "type": "keyword"
    },
    "profiles": {
      "type": "keyword"
    },
    "sic": {
      "properties": {
        "industry_group": {
          "type": "keyword"
        },
        "industry_sector": {
          "type": "keyword"
        },
        "major_group": {
          "type": "keyword"
        },
        "sic_code": {
          "type": "keyword"
        }
      }
    },
    "size": {
      "type": "keyword"
    },
    "size_range_int": {
      "type": "integer"
    },
    "summary": {
      "type": "text"
    },
    "tags": {
      "type": "keyword",
      "ignore_above": 256,
      "fields": {
        "text": {
          "type": "text"
        }
      }
    },
    "ticker": {
      "type": "keyword",
      "normalizer": "lowercase"
    },
    "twitter_url": {
      "type": "keyword"
    },
    "type": {
      "type": "keyword"
    },
    "ultimate_parent": {
      "type": "keyword"
    },
    "website": {
      "type": "keyword"
    }
  }
}

All Field Descriptions

See this section.