---
title: "Search companies"
method: POST
path: "/api/v1/companies/search"
tags: ["Search"]
---

# Search companies

`POST /api/v1/companies/search`

## Request

- Base URL: `https://app.getleads.io`
- URL: `https://app.getleads.io/api/v1/companies/search`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

One row per company domain. Company-level filters only
(industries, headquarters, size, domain, funding, …).
Person-level filters (`job_titles`, `seniority`, …) return 400 —
use `/api/v1/contacts/search` for people. Charges 1 credit per
company returned. `contact_count` is the number of matching
contact rows at that company.

## Request body

- object: Contact search filters. All fields are optional. At least one filter or `where_sql` is required. Filters can be top-level or nested under a `filters` object (both are merged).
  - `domains` string[]
  - `job_titles` string[]
  - `seniority` string[]
  - `job_functions` string[]
  - `industries` string[]
  - `countries` string[]
  - `headquarters_countries` string[]
  - `company_size` string[]: LinkedIn size-band labels (e.g. "51 to 200").
  - `company_linkedin_urls` string[]
  - `revenue` string[]
  - `cities` string[]
  - `states` string[]
  - `exclude_domains` string[]
  - `exclude_countries` string[]
  - `exclude_headquarters_countries` string[]
  - `exclude_industries` string[]
  - `exclude_job_titles` string[]
  - `email_status` string[]: Email verification status. Use ["VALID"] for deliverable emails.
  - `technologies` string[]: Technologies/tools a company uses.
  - `funding_types` string[]: Last funding round type (e.g. "Seed", "Series A", "IPO").
  - `headquarters_cities` string[]
  - `company_name` string
  - `email_domain` string
  - `first_name` string
  - `last_name` string
  - `email_address` string
  - `linkedin_url` string
  - `company_description` string: Keyword search over company LinkedIn About text.
  - `person_description` string: Keyword search over person LinkedIn bio.
  - `linkedin_headline` string
  - `education` string
  - `certifications` string
  - `languages` string
  - `job_start_date_min` string, date: Earliest current-role start date (YYYY-MM-DD).
  - `job_start_date_max` string, date: Latest current-role start date (YYYY-MM-DD).
  - `skills` string: Keyword search over contact skills.
  - `domain_list_id` string: Saved domain list id.
  - `company_size_min` integer
  - `company_size_max` integer
  - `employees_min` integer: Minimum company headcount (band-overlap matching).
  - `employees_max` integer: Maximum company headcount (band-overlap matching).
  - `employee_profiles_on_linkedin_min` integer: Minimum exact LinkedIn employee-profile headcount (hard cutoff).
  - `employee_profiles_on_linkedin_max` integer: Maximum exact LinkedIn employee-profile headcount (hard cutoff).
  - `founded_year_min` integer: Earliest founding year.
  - `founded_year_max` integer: Latest founding year.
  - `total_funding_min` integer: Minimum total funding raised (USD).
  - `total_funding_max` integer: Maximum total funding raised (USD).
  - `require_email` boolean
  - `require_phone` boolean
  - `require_company_profile` boolean: Skip contacts with no company name. Defaults on for domain-only searches that request company columns.
  - `require_domain_or_headline` boolean: Rank contacts with a company domain or LinkedIn headline first; remaining matches still appear later. Defaults on for the new database.
  - `has_mobile_app` boolean
  - `has_web_app` boolean
  - `open_to_work` boolean: Only contacts with LinkedIn Open to Work signal.
  - `is_hiring` boolean: Only contacts with LinkedIn Hiring badge.
  - `limit` integer
  - `offset` integer
  - `columns` string[]: Company columns only. Discover with GET /api/v1/companies/columns.
  - `where_sql` string

## Response `200`

Matching companies

- object
  - `ok` boolean
  - `companies` object[]
  - `total_available` integer
  - `total_available_is_minimum` boolean
  - `query_credits_used` integer
  - `creditsRemaining` integer, nullable
  - `offset` integer
  - `limit` integer
  - `returned` integer
  - `has_more` boolean
  - `next_offset` integer

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key
- `402`: Insufficient credits or fair-use limit reached
- `429`: Rate limit exceeded
- `502`: Upstream timeout or database error

---

[API](https://skmtc.dev/getleads/apis/getleads-api.md) - [All operations](https://skmtc.dev/getleads/apis/getleads-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getleads/apis/getleads-api/revisions/f5dbc32e0c3a?raw)