> ## Documentation index
> Fetch the complete documentation index at: https://docs.leadmcp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search companies

`POST /companies/search`

Returns one page of company records for a company filter, in a fixed order. Each returned company costs one contact credit, through the same plan caps as contacts. Page with `cursor` until `page.next_cursor` is null. To find the people at these companies, send their ids to `POST /contacts/search` in the `company_ids` filter key.

Returns one page of company records for a company filter, in a fixed order. Each returned company costs one contact credit, through the same plan caps as contacts. Page with `cursor` until `page.next_cursor` is null. To find the people at these companies, send their ids to `POST /contacts/search` in the `company_ids` filter key.

Cost: Each returned company costs one contact credit.

## Request body

- `filter` | CompanyFilter | required. The companies to read.
  - `company_ids` | array of CompanyId | optional. Company ids (`com_`) to include. Takes up to 1,000 ids.
  - `domains` | array of string | optional. Company domains. A company matches when any of its domains is in the list. A full URL reduces to a bare domain on input.
  - `exclude_domains` | array of string | optional. Company domains to exclude. A company is left out when any of its domains is in the list.
  - `company_names` | array of string | optional. Company names. Case-insensitive exact match after normalization. Lowercase, trim and collapse whitespace. Strip one trailing legal suffix with an optional comma, then a leading "the ". Legal suffixes: inc, inc., incorporated, llc, l.l.c., ltd, ltd., limited, corp, corp., corporation, co, co., gmbh, ag, sa, s.a., bv, b.v., plc, pty ltd, srl. An empty normalized name returns 400 request.invalid. Values are OR within this key and AND across keys.
  - `exclude_company_names` | array of string | optional. The NOT of company_names after the same normalization. Lowercase, trim and collapse whitespace. Strip one trailing legal suffix with an optional comma, then a leading "the ". Legal suffixes: inc, inc., incorporated, llc, l.l.c., ltd, ltd., limited, corp, corp., corporation, co, co., gmbh, ag, sa, s.a., bv, b.v., plc, pty ltd, srl. An empty normalized name returns 400 request.invalid. Values are OR within this key and AND across keys.
  - `company_size` | array of CompanySize | optional. Company employee bands to include. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `10K+`.
  - `company_revenue` | array of CompanyRevenue | optional. Company revenue ranges to include. Only companies with a known revenue range match; most small companies have none, so this key leaves them out. Values: `0-1M`, `1M-10M`, `10M-50M`, `50M-100M`, `100M-1B`, `1B+`.
  - `industries` | array of Industry | optional. Company industries to include, as slugs such as software_development. A label such as 'Software Development' or 'IT Services & IT Consulting' is folded to its slug. Read the values from GET /companies/schema/industries/values.
  - `exclude_industries` | array of Industry | optional. Company industries to exclude, as slugs such as software_development. A label such as 'Software Development' or 'IT Services & IT Consulting' is folded to its slug. Read the values from GET /companies/schema/industries/values.
  - `employee_count_min` | integer | optional. The smallest company employee count, inclusive.
  - `employee_count_max` | integer | optional. The largest company employee count, inclusive.
  - `founded_year_min` | integer | optional. The earliest company founding year, inclusive.
  - `founded_year_max` | integer | optional. The latest company founding year, inclusive.
  - `company_hq_countries` | array of Country | optional. Company headquarters countries to include. Send ISO-2 codes such as us, or English names such as Germany.
  - `last_round_after` | YearMonth | optional. The latest financing event is after this month, exclusive.
  - `last_round_before` | YearMonth | optional. The latest financing event is before this month, exclusive.
  - `last_round_types` | array of FundingRoundType | optional. Types of the latest financing event to include. Values: `pre_seed`, `seed`, `series_a`, `series_b`, `series_c_plus`, `private_equity`, `debt`, `other`.
  - `total_funding_min` | integer | optional. The smallest total funding in US dollars, inclusive. Missing funding is null and never matches.
  - `total_funding_max` | integer | optional. The largest total funding in US dollars, inclusive.
- `limit` | integer | optional. The page size. The default is 50 and the maximum is 500, the same as contact search. Default `50`.
- `cursor` | Cursor | optional. The cursor from the previous page. Omit it on the first page. Read pages until `page.next_cursor` is null.

## Response

One page of company records.

- `id` | CompanyId | optional. Our company id. Send it to the contact filter in company_ids.
- `name` | string or null | optional. The company name.
- `description` | string or null | optional. The company description.
- `domain` | string or null | optional. The company domain.
- `domains` | array of string | optional. The company domains.
- `linkedin` | string or null | optional. The company linkedin.
- `linkedin_urls` | array of string | optional. The company linkedin urls.
- `social` | array of object | optional. The company social.
  - `network` | string or null | optional. The network.
  - `url` | string or null | optional. The url.
  - `username` | string or null | optional. The username.
  - `followers` | integer or null | optional. The followers.
- `phone` | string or null | optional. The company phone.
- `employee_count` | integer or null | optional. The company employee count.
- `headcount_band` | CompanySize (slug) or null | optional. The company employee band.
- `founded_year` | integer or null | optional. The company founded year.
- `revenue_range` | CompanyRevenue (slug) or null | optional. The yearly revenue range of the company. Null when it is not known, which is the case for most small companies.
- `employee_growth_pct` | integer or null | optional. The change in the employee count over the latest month, in percent. Negative when the company shrank. Null when unknown.
- `hq_city` | string or null | optional. The company hq city.
- `hq_country` | string or null | optional. The company hq country.
- `locations` | array of object | optional. The company locations.
  - `name` | string or null | optional. The name.
  - `country` | string or null | optional. The country.
  - `is_primary` | boolean or null | optional. The is primary.
  - `street` | string or null | optional. The street address. Null when the location is not the address on record.
  - `postcode` | string or null | optional. The postal code. Null when the location is not the address on record.
- `industries` | array of string | optional. The company industries.
- `naics` | array of string | optional. The NAICS industry codes.
- `specialties` | array of string | optional. What the company says it specializes in, in its own words.
- `is_nonprofit` | boolean or null | optional. Whether the company is nonprofit. Null when unknown.
- `is_government` | boolean or null | optional. Whether the company is government. Null when unknown.
- `is_public` | boolean or null | optional. Whether the company is public. Null when unknown.
- `total_funding_usd` | integer or null | optional. The company total funding usd.
- `last_round_type` | FundingRoundType (slug) or null | optional. The latest funding round category.
- `last_round_usd` | integer or null | optional. The company last round usd.
- `last_round_date` | CalendarDate or null | optional. The latest funding date.
- `investors` | array of string | optional. The lead investors of the company's funding rounds.
- `investor_count` | integer or null | optional. The number of investors in the latest funding round. Null when unknown.
- `monthly_visits` | integer or null | optional. The company monthly visits.
- `sic` | array of string | optional. The SIC industry codes.
- `last_updated` | YearMonth or null | optional. The month the company record changed.

## Failures

| Status | Meaning |
| --- | --- |
| `400` | The request shape, a filter key, a value, a cursor or the enrichment mode was rejected. |
| `401` | The credential is missing, unknown or revoked. |
| `402` | The daily or the monthly contact credit cap is spent, or the free plan's lifetime pool is. |
| `422` | The filter was rejected before it ran: more than 32 predicates, deeper than 4, more than 25 leaves, more than 1,000 domains or company names, more than 50 values in another list, a leading wildcard in a where leaf, a leading or trailing wildcard in title_query, an operator, value type or shape the column does not take, a leaf other than exists with no value, or an empty `and` or `or` group. |
| `429` | The key passed 300 requests a minute or 2 concurrent requests. |
| `503` | The data is unavailable for a short time. |
| `504` | The query passed its time budget and was stopped. |

## Example

```bash
curl -sS -X POST "https://api.leadmcp.ai/v1/companies/search" \
  -H "Authorization: Bearer lm_live_YOUR_API_KEY" \
  -H "LeadMCP-Version: 2026-09-19" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"company_hq_countries":["us"],"company_size":["51-200","201-500"],"industries":["software_development"]},"limit":25}'
```

Response `200`:

```json
{
  "ok": true,
  "request_id": "req_01JBQ2W8K9V6M3T0X5Y7Z4A1BC",
  "release": "b_2026_09_15",
  "data": [
    {
      "id": "com_01JBQ2W8K9V6M3T0X5Y7Z4A1BC",
      "name": "Dana Reyes",
      "description": "description",
      "domain": "domain",
      "domains": [
        "domains"
      ],
      "linkedin": "https://www.linkedin.com/in/dana-reyes",
      "linkedin_urls": [
        "linkedin urls"
      ],
      "social": [
        {
          "network": "network",
          "url": "url",
          "username": "username",
          "followers": 1
        }
      ],
      "phone": "phone",
      "employee_count": 320,
      "headcount_band": "1-10",
      "founded_year": 0,
      "revenue_range": "0-1M",
      "employee_growth_pct": 1,
      "hq_city": "hq city",
      "hq_country": "hq country",
      "locations": [
        {
          "name": "Dana Reyes",
          "country": "us",
          "is_primary": true,
          "street": "street",
          "postcode": "postcode"
        }
      ],
      "industries": [
        "industries"
      ],
      "naics": [
        "naics"
      ],
      "specialties": [
        "specialties"
      ],
      "is_nonprofit": true,
      "is_government": true,
      "is_public": true,
      "total_funding_usd": 0,
      "last_round_type": "pre_seed",
      "last_round_usd": 0,
      "last_round_date": "2026-09-19",
      "investors": [
        "investors"
      ],
      "investor_count": 0,
      "monthly_visits": 0,
      "sic": [
        "sic"
      ],
      "last_updated": "2026-08"
    }
  ],
  "page": {
    "returned": 50,
    "limit": 50,
    "total": 4210,
    "next_cursor": "eyJ2IjoxLCJiIjoiYl8yMDI2XzA5XzE1In0"
  },
  "quota": {
    "plan": "free",
    "contact_credits_used": 50,
    "month_remaining": 950,
    "today_remaining": 950,
    "binding": "month",
    "resets_at": "9999-12-31T23:59:59.000Z"
  },
  "warnings": []
}
```