Find companies

Search the Icypeas database for companies matching your criteria: industry, location, headcount, growth, revenue… Counting is free, each result fetched costs 0.02 credit.

How to use it:

1. Build a query with the filters below.
2. Call /find-companies/count to see how many companies match. It's free, so tweak your filters until the number looks right.
3. Call /find-companies to get the results, 100 per page by default (up to 200). Use the pagination token to get the next pages.

info

Unlike email searches, these endpoints answer immediately: no waiting, no second call. See the rate limits.

Available filters

Below is the list of available filters that can be used to search the companies dataset:

Filter name	Description	Type	Examples	Constraints
name	The company name	Include/Exclude	"name": { "include": ["icypeas", "bell security solutions inc."], "exclude": ["apple"] }	This is an open field. You can put whatever you want
lid	The Linkedin company public ID	Include/Exclude	"lid": { "include": ["google"] }	The ID can be found at the end of URLs like https://www.linkedin.com/company/google. Here the ID is google.
urn	The Linkedin company URN (numerical ID)	Include/Exclude	"urn": { "exclude": ["1527"] }	This is a numerical ID only.
companyId	An id matching a company	Include/Exclude	"companyId": { "include": ["https://www.icypeas.com", "5678", "icypeas", "https://linkedin.com/company/icypeas"] }	This is a textual field. It should contain valid ids. We support: company domain or website / URN numeric id / LinkedIn URL of the company / Directly the company vanity name: https://linkedin.com/company/icypeas -> icypeas.
type	The company type (Privately Held, Public Company, ...)	Include/Exclude	"type": { "include": ["Privately Held"], "exclude": ["Public Company"] }	Available types are: Privately Held, Sole Proprietorship, Self-Employed, Partnership, Public Company, Nonprofit, Educational Institution, Government Agency
industry	The company industry (Software development, ...)	Include/Exclude	"industry": { "include": ["Real Estate"] }	The list of available industries can be downloaded here
location	The company headquarters' location	Include/Exclude	"location": { "include": ["US", "Paris, France"] }	You can put the name of a city, a country, a state, but for best results we strongly advised to use alpha-2 country code (IN, FR, US, ...). Use a comma to narrow a location down, see below
headcount	The company headcount	Range	"headcount": { ">": 10 }	This is a range of integers. Please see how to define a range here
headcountGrowth	The headcount growth (in percentage) for a company in a given timespan (6 months, 12 months, 24 months)	HeadCountGrowth	"headcountGrowth": { "min": -10, "max": 50, "timespan": "6months" }	This is a HeadCountGrowth kind of type . Please see how to define it here
revenue	The revenue of the company	Range	"revenue": { ">": 1000000 }	This is a range of integers. Please see how to define a range here
keyword	A special filter that search across the entire company profile (name, description, specialties, ...)	Include/Exclude	"keyword": { "include": ["Higer education"] }	This is an open text field, you can put whatever you want.
domain	The company website or domain	Include/Exclude	"keyword": { "include": ["icypeas.com"] }	We strongly advise to use the web domain and not a formatted URL (i.e. use icypeas.com instead of https://www.icypeas.com).

Narrowing a location down

A location made of comma separated parts only matches when every one of its parts does. "Paris, France" matches the companies whose headquarters are in Paris and in France, which is how you tell the French Paris from Paris, Texas.

Each part is matched against the country, the state and the city of the company, so the order of the parts does not matter: "Paris, France" and "France, Paris" are the same filter.

Several locations remain alternatives to each other, whether they hold a comma or not. "location": { "include": ["Paris, France", "US"] } matches the companies located in Paris (France) or anywhere in the United States.

Query examples

Search for all companies headquartered in Paris, France

{
    "query": {
        "location": { "include": ["Paris, France"] }
    }
}

Search for all companies named icypeas or apple

{
    "query": {
        "name": { "include": ["icypeas", "apple"] }
    }
}

Search for all privately held companies that have more than 10 employees

{
    "query": {
        "type": { "include": ["Privately Held"] },
        "headcount": { ">": 10 }
    }
}

Search for all companies excluding self-employed people that work in the real estate industry

{
    "query": {
        "type": { "exclude": ["Self-Employed"] },
        "industry": { "include": ["Real Estate"] }
    }
}

Search for a specific company using it's public ID

{
    "query": {
        "lid": { "include": ["google"] },
    }
}

Search for a specific company using it's numerical URN

{
    "query": {
        "urn": { "include": ["1527"] },
    }
}

Count matching companies (free)

When you need to assess the number of companies returned by a specific query, you should use this route. We do not charge anything when using this route.

POSThttps://app.icypeas.com/api/find-companies/count

Headers

• Authorizationstringrequired

  Your API key, as is (no Bearer prefix).

• Content-Typestringrequired

  Always application/json.

Body parameters

• queryobjectrequired

  The query

  Rule: should be a valid query (see available fields above)

Request example

cURL

curl -X POST "https://app.icypeas.com/api/find-companies/count" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY"

JavaScript

const response = await fetch("https://app.icypeas.com/api/find-companies/count", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "YOUR_API_KEY",
  },
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://app.icypeas.com/api/find-companies/count",
    headers={"Authorization": "YOUR_API_KEY"},
)
print(response.json())

PHP

<?php
$ch = curl_init("https://app.icypeas.com/api/find-companies/count");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: YOUR_API_KEY",
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

PowerShell

$headers = @{
  "Authorization" = "YOUR_API_KEY"
  "Content-Type"  = "application/json"
}

$response = Invoke-RestMethod -Method POST -Uri "https://app.icypeas.com/api/find-companies/count" -Headers $headers
$response | ConvertTo-Json -Depth 10

Responses

200SuccessResponse when they are no errors

Example response · 200

{
  "success": true,
  "total": 10
}

Response fields

• successboolean

  true means that your search succeeded (no error was raised on our side)

• totalnumber

  The number of companies

200Validation errorResponse when there are validation errors.

The request reached Icypeas but some fields are wrong. The response lists every problem in validationErrors. See how to read and fix errors.

Example response · 200

{
  "validationErrors": [
    {
      "expected": "object with props defined in the schema",
      "type": "objectStrict",
      "actual": {
        "x": 10
      },
      "field": "query.headcount",
      "message": "The object 'query.headcount' contains forbidden keys."
    }
  ],
  "success": false
}

Type	Fields	When it happens
required	query	Error sent when the query field is not passed inside the request body
EmptyQueryError	query	Error sent when the query is empty
objectStrict	query.[field]	Error sent when a field contains forbidden keys (for instance { urn: { x: ["test"] } } instead of { urn: { exclude: ["test"] } })
arrayEmpty	query.[field].includequery.[field].exclude	Error sent when a Include/Exclude field contains an empty include or exclude array
objectLength	query.[field]	Error sent when a field is empty (for instance { urn: {} } instead of { urn: { include: ["1527"] } })
InsufficientCredits		You need more credits than the ones you have to run this search.
UnpaidSubscriptionError		Error sent when you have a pending payment and your subscription is therefore not paid

401UnauthorizedResponse when we could not authenticate you.

Example response · 401

{
  "message": "Unauthorized access.",
  "error": "UnauthorizedAccessError",
  "status": 401,
  "code": "unauthorized_access_error"
}

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code

429Too many requestsError received when rate limit is exceeded

Example response · 429

{
  "message": "You have exceeded the max number of requests per minute.",
  "error": "RateLimitExceededError",
  "status": 429,
  "code": "rate_limit_exceeded_error"
}

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code

Fetch matching companies

When you want to retrieve the results for your query, you should use this route. The route is paginated, please see below on how to handle pagination.

POSThttps://app.icypeas.com/api/find-companies

Headers

• Authorizationstringrequired

  Your API key, as is (no Bearer prefix).

• Content-Typestringrequired

  Always application/json.

Body parameters

• queryobjectrequired

  The query

  Rule: should be a valid query (see available fields above)

• paginationobjectoptional

  This is optional and used only if you want to retrieve more companies than the first page.

  Rule: should be a valid pagination object

  Show properties (2)

  • tokenstringrequired

    The token returned with the previous page. Valid 15 minutes; each response returns a new token with a new 15-minute validity.

    Rule: should be a valid pagination token

  • sizenumberoptional

    The number of companies returned per page

    Rule: should be a valid integer between 1 and 200

    Default: 100

Request example

cURL

curl -X POST "https://app.icypeas.com/api/find-companies" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY"

JavaScript

const response = await fetch("https://app.icypeas.com/api/find-companies", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "YOUR_API_KEY",
  },
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://app.icypeas.com/api/find-companies",
    headers={"Authorization": "YOUR_API_KEY"},
)
print(response.json())

PHP

<?php
$ch = curl_init("https://app.icypeas.com/api/find-companies");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: YOUR_API_KEY",
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

PowerShell

$headers = @{
  "Authorization" = "YOUR_API_KEY"
  "Content-Type"  = "application/json"
}

$response = Invoke-RestMethod -Method POST -Uri "https://app.icypeas.com/api/find-companies" -Headers $headers
$response | ConvertTo-Json -Depth 10

Responses

200SuccessResponse when no errors are sent

Example response · 200

{
  "success": true,
  "total": 845,
  "leads": [
    {
      "name": "Harvard Graduate School of Education",
      "lid": "hgse",
      "urn": "urn:li:fs_salesCompany:1653",
      "url": "https://www.linkedin.com/company/hgse/",
      "description": "Education touches every aspect of human activity. At the Harvard Graduate School of Education (HGSE), we believe studying and improving the enterprise of education are central to the health and future of society.",
      "address": "Cambridge, Massachusetts, United States",
      "numberOfEmployees": 1134,
      "industry": "Higher Education",
      "website": "http://www.gse.harvard.edu",
      "specialties": [],
      "employeeGrowth": [],
      "_id": "sMMXT5MBIateb5xQKCCK"
    },
    {
      "name": "Trammell Crow Company",
      "lid": "trammell-crow-company",
      "urn": "urn:li:fs_salesCompany:2320",
      "url": "https://www.linkedin.com/company/trammell-crow-company/",
      "description": "Trammell Crow Company (TCC) is a global commercial real estate developer and wholly-owned subsidiary of CBRE Group, Inc. (NYSE:CBRE), a Fortune 500 and S&P 500 company headquartered in Dallas. Founded in 1948, TCC has developed or acquired nearly 2,900 buildings valued at $75 billion and over 655 million square feet. As of September 30, 2024, TCC had $19 billion of projects in process and $13.4 billion in its pipeline. With 575 employees throughout the United States and Europe in 27 offices, the company serves users of and investors in office, industrial/logistics, healthcare, life science, data center and mixed-use projects, as well as multi-family residential through its operating subsidiary High Street Residential. For more information visit www.TrammellCrow.com.",
      "address": "Dallas, Texas, United States",
      "numberOfEmployees": 989,
      "industry": "Real Estate",
      "website": "http://www.trammellcrow.com",
      "specialties": [],
      "employeeGrowth": [],
      "_id": "-sMXT5MBIateb5xQeCIO"
    }
  ],
  "pagination": {
    "size": 2,
    "token": "xxxxxx"
  }
}

Response fields

• successboolean

  true means that your search succeeded (no error was raised on our side)

• totalnumber

  The number of companies

• paginationobject

  This is used if you want to retrieve more companies than the first page.

  Show properties (2)

  • tokenstring

    Token to request the next page. Valid 15 minutes from this response: request the next page before it expires.

  • sizenumber

    The number of companies returned per page

    Default: 100

• leadsarray of objects

  An array containing the companies information

  Show item properties (19)

  • _idstring

    Icypeas unique identifier.

  • namestring

    Company name

  • urlstring

    LinkedIn company URL.

  • urnstring

    LinkedIn company URN.

  • websitestring

    Company website

  • phonestring

    Main phone number given by the company (unnormalized, we keep what was given)

  • industrystring

    Company industry

  • foundedYearnumber

    Company founded year (-1 when not known)

  • specialtiesarray of objects

    Company specialties

    Show item properties (1)

    • valuestring

      Data value.

  • lidstring

    LinkedIn ID (the `my-linkedin-id` in https://linkedin.com/company/my-linkedin-id).

  • descriptionstring

    Company description.

  • pictureUrlstring

    Company image URL.

  • typestring

    Company legal form (LLC, SAS, SARL, GmbH, ...)

  • addressstring

    Company headquarters address

  • numberOfEmployeesnumber

    Number of employees (-1 when not known).

  • headcountRangestring

    Declarative headcount range (e.g. 1-10 or 50-100)

  • estimatedRevenuRangeobject

    Estimated revenue

    Show properties (2)

    • estimatedMaxRevenueobject

      Estimation of max revenue

      Show properties (3)

      • amountnumber

        Amount

      • unitstring

        Amount unit (BILLION, MILLION, THOUSAND, ...)

      • currencystring

        Amount currency (three letters)

    • estimatedMinRevenueobject

      Estimation of min revenue

      Show properties (3)

      • amountnumber

        Amount

      • unitstring

        Amount unit (BILLION, MILLION, THOUSAND, ...)

      • currencystring

        Amount currency (three letters)

  • revenueobject

    When the revenue is known (because the company has to disclose it, for instance)

    Show properties (3)

    • amountnumber

      Amount

    • unitstring

      Amount unit (BILLION, MILLION, THOUSAND, ...)

    • currencystring

      Amount currency (three letters)

  • employeeGrowtharray of objects

    Employee growth over the year

    Show item properties (1)

    • growthobject

      employee growth for a given timespan

      Show properties (2)

      • percentagenumber

        Employee growth percentage

      • timespanstring

        Time span (SIX_MONTHS, YEAR, TWO_YEAR, ...)

200Validation errorResponse when there are validation errors.

The request reached Icypeas but some fields are wrong. The response lists every problem in validationErrors. See how to read and fix errors.

Example response · 200

{
  "validationErrors": [
    {
      "expected": "object with props defined in the schema",
      "type": "objectStrict",
      "actual": {
        "x": 10
      },
      "field": "query.headcount",
      "message": "The object 'query.headcount' contains forbidden keys."
    }
  ],
  "success": false
}

Type	Fields	When it happens
required	query	Error sent when the query field is not passed inside the request body
EmptyQueryError	query	Error sent when the query is empty
objectStrict	query.[field]	Error sent when a field contains forbidden keys (for instance { urn: { x: ["test"] } } instead of { urn: { exclude: ["test"] } })
arrayEmpty	query.[field].includequery.[field].exclude	Error sent when a Include/Exclude field contains an empty include or exclude array
objectLength	query.[field]	Error sent when a field is empty (for instance { urn: {} } instead of { urn: { include: ["1527"] } })
InsufficientCredits		You need more credits than the ones you have to run this search.
UnpaidSubscriptionError		Error sent when you have a pending payment and your subscription is therefore not paid
number	pagination.size	Error sent when the size in pagination is not an integer
numberMin	pagination.size	Error sent when pagination is less than the min
numberMax	pagination.size	Error sent when pagination is greater than the max
InvalidPaginationTokenError	pagination.token	Error sent when the pagination token is not in the right format

401UnauthorizedResponse when we could not authenticate you.

Example response · 401

{
  "message": "Unauthorized access.",
  "error": "UnauthorizedAccessError",
  "status": 401,
  "code": "unauthorized_access_error"
}

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code

429Too many requestsError received when rate limit is exceeded

Example response · 429

{
  "message": "You have exceeded the max number of requests per minute.",
  "error": "RateLimitExceededError",
  "status": 429,
  "code": "rate_limit_exceeded_error"
}

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code

Pagination

Results come in pages of pagination.size items (100 by default, from 1 to 200). With 1,000 matches and the default size, you need 10 calls to get everything.

When there are more results, the response contains a pagination object with a token. Send that object back with the same query to get the next page:

1. First request

{
  "query": { "headcount": { ">": 10 } },
  "pagination": { "size": 2 }
}

1. First response (shortened)

{
  "success": true,
  "total": 845,
  "leads": [
    { "name": "Harvard Graduate School of Education", "numberOfEmployees": 1134, "industry": "Higher Education" },
    { "name": "Trammell Crow Company", "numberOfEmployees": 989, "industry": "Real Estate" }
  ],
  "pagination": {
    "size": 2,
    "token": "eyJzYSI6W1syXSxbMTI4ODQ5MDE5MDJdXSwiaWQiOi…"
  }
}

2. Next request: same query + the pagination object you received

{
  "query": { "headcount": { ">": 10 } },
  "pagination": {
    "size": 2,
    "token": "eyJzYSI6W1syXSxbMTI4ODQ5MDE5MDJdXSwiaWQiOi…"
  }
}

Each response brings a new token: always use the latest. Stop when no pagination object comes back.

Token expiration

A token is valid for 15 minutes. Every request that uses it returns a new token, with a fresh 15-minute window.

So the 15 minutes is the maximum time between two pages, not the time you have to go through the whole search. As long as you ask for the next page within 15 minutes of the previous one, you can keep paging for as long as you need, even to retrieve hundreds of thousands or millions of results.

Request	Uses token	Returns token	Valid until
Page 1 at 10:00	none	A	10:15
Page 2 at 10:12	A	B	10:27
Page 3 at 10:20	B	C	10:35
…	…	…	…

If a token expires, start again from the first page with the same query.

warning

• Always send the latest token. An older one may have expired even if you're still paging.
• Don't change the query between pages: the token belongs to that exact query.
• Pausing your script for more than 15 minutes between two pages (for example while processing a batch) makes the token expire.

Include/Exclude specs

The Include/Exclude field can contains two arrays:

1. include array which lists what needs to be included in the query.
2. exclude array which lists what needs to be excluded from the query.

For instance, when looking for leads, you can include some currentJobTitle and exclude some others:

{
    "currentJobTitle": {
        "include": ["CTO"],
        "exclude": ["Senior engineer"]
    }
}

caution

include and exclude arrays are limited to 200 values per array per field.

Range specs

The Range field contains comparison operators and numerical values only. Some examples are listed below:

{
    "headcount": {
        ">=": 10,
        "<": 20
    }
}

{
    "headcount": {
        ">": 10,
        "<=": 20
    }
}

{
    "headcount": {
        ">": 10,
        "<": 20
    }
}

The operators can be > (greater than), < (less than), >= (greater or equal), <= (less or equal).

You are responsible for giving a range that makes sense.

Headcount growth specs

Filter companies by their employee growth rate over a specific period. This criterion is useful for identifying scaling companies, detecting workforce reductions, or finding organizations at particular growth stages.

Headcount growth parameters

Parameter	Type	Description
timespan	string	The measurement period: 6months, 12months, or 24months
min	number	Minimum growth rate (percentage). Range: -100 to 10,000
max	number	Maximum growth rate (percentage). Range: -100 to 10,000

Growth rate scale

• 0% = No change in headcount
• Positive values = Headcount increase
• Negative values = Headcount decrease
• -100% = Company lost all employees

Headcount growth example

{
  "headcountGrowth": {
    "timespan": "6months",
    "min": -10,
    "max": 50
  }
}

Returns all companies that experienced between -10% and +50% headcount growth in the past 6 months.