Skip to Content
CompanySpec
API referenceDiscovery

Search companies

POST
/companies/search

Find companies with filters, a plain-language semantic_query, or both.

Order. With semantic_query, results are sorted by match.score (relevance, blended with company size and web traffic by semantic_weight). Without it, larger companies with more web traffic come first. query and semantic_query can be used together: query narrows by name or domain, semantic_query ranks.

Cost. 1 discovery per company returned that isn't already paid for this billing month, including companies on later pages. The show_* options cost nothing extra. Use /companies/count first; it's free.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Your API key, sent as Authorization: Bearer <key>. Create keys in the dashboard.

Request Body

application/json
  1. body

Filters shared by search, count, similar, page search and job search. Different filters are combined with AND. Inside one list, values match if the company has any of them, unless the filter has an *_operator (then the default is and: the company must have all of them).

query?string

Match against company name and domain (contains).

Lengthlength <= 250
semantic_query?string

Describe the companies you want in plain language, including who they sell to.

Lengthlength <= 500
semantic_weight?number

How much to favour relevance to semantic_query (1) over company size and web traffic (0).

Range0 <= value <= 1
Default0.7
countries?array<string>

HQ countries (ISO 3166-1 alpha-2). Matches any.

states?array<string>

Values from /values/states. Matches any.

cities?array<string>

Values from /values/cities. Matches any.

regions?array<string>

Values from /values/regions. Matches any.

office_locations?array<string>

Any office, not just HQ. Values from /values/cities or country codes. Matches any.

type?array<>

Ownership type. Matches any. Values from /values/type.

employees?array<>

Employee ranges. Matches any. Values: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.

revenue?array<>

Annual revenue ranges (USD). Matches any. Values: under-1m, 1m-10m, 10m-50m, 50m-100m, 100m-200m, 200m-1b, over-1b.

founded_year?

Year of the most recent round.

industries?array<string>

Values from /values/industries. Matches any.

naics_codes?array<>

2–6 digits. Shorter codes include all codes beneath them. Matches any.

sic_codes?array<>

Values from /values/sic_codes. Matches any.

keywords?array<string>

Keywords from the company profile. Combined with keywords_operator.

keywords_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
customer_types?array<string>

Who they sell to: B2B, B2C, B2G. Combined with customer_types_operator.

customer_types_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
customer_segments?array<string>

Kinds of customers, for example enterprise, smb, government. Values from /values/customer_segments. Combined with customer_segments_operator.

customer_segments_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
compliance?array<string>

Claimed certifications, for example SOC 2, HIPAA. Values from /values/compliance. Combined with compliance_operator.

compliance_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
technologies?array<string>

Technology slugs from /technologies. Combined with technologies_operator.

technologies_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
technology_source?string

Where a technology must have been found: website, jobs or any (default).

Default"any"
Value in"website""jobs""any"
vendors?array<string>

Service providers named in the subprocessor list (slugs from /technologies). Combined with vendors_operator.

vendors_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
page_types?array<>

The company must have all of these page types.

funding_rounds?array<>

Has raised any of these round types. Values from /values/funding_rounds.

funding_amount?

Year of the most recent round.

funding_year?

Year of the most recent round.

investors?array<string>

Backed by any of these investors (names or domains).

workforce_size?array<>

Headcount ranges per department, for example [{"department": "engineering", "min": 20}]. Departments from /values/workforce_departments, or overall. All conditions must match.

workforce_growth?

Headcount growth over a period (m6 = 6 months, y1 = 1 year, y2 = 2 years), optionally for one department, as a percentage range.

recent_hires?

Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.

hiring?

Companies with matching open job postings.

news?

Companies with matching news events.

require?array<>

Only return companies that have these: linkedin (LinkedIn URL), twitter (Twitter/X URL), icp (ICP paragraph), pricing_page (pricing page summary), funding (funding data), revenue (revenue range), founded_year, hq_city, open_jobs (at least one open job posting).

exclude?

Remove companies that match any of these, for example {"domains": ["acme.com"], "employees": ["1-10"]}.

limit?integer

Results per page (1–100). A search returns at most 1,000 results in total.

Range1 <= value <= 100
Default25
cursor?string

The next_cursor from the previous page.

min_score?number

Minimum match.score (0–1). For semantic_query it is relevance; for /companies/similar it is similarity to the seeds.

Range0 <= value <= 1
show_icp?boolean

Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost.

Defaultfalse
show_pricing?boolean

Include the pricing summary in each result. No extra cost.

Defaultfalse
show_description?boolean

Include the long description in each result. No extra cost.

Defaultfalse
show_pages?boolean

Include the list of most useful pages on their website in each result. No extra cost.

Defaultfalse

Response Body

Matching companies.

application/json
  1. response
results*array<>
next_cursor*|

Pass as cursor to get the next page. null when there are no more results.

usage*

What this request cost and what is left this billing month.

Example Request
curl -X POST 'https://api.companyspec.com/v1/companies/search' \  -H 'Content-Type: application/json' \  -d '{  "semantic_query": "practice management software for independent dental practices",  "countries": [    "US"  ],  "employees": [    "11-50",    "51-200"  ],  "customer_types": [    "B2B"  ],  "compliance": [    "HIPAA"  ],  "exclude": {    "domains": [      "acmedental.io"    ]  },  "limit": 25}'
Example Response
{  "results": [    {      "company": {        "id": "cmp_4kq7p",        "domain": "bracehub.com",        "name": "BraceHub",        "website": "https://bracehub.com",        "description": "Scheduling and patient communication software for orthodontic and dental practices.",        "logo_url": null,        "type": "private",        "founded_year": 2019,        "ipo_date": null,        "industry": "Software Development",        "industries": [          "Software Development",          "Healthcare Technology"        ],        "naics_codes": [          "513210"        ],        "sic_codes": [          "7372"        ],        "keywords": [          "orthodontic software",          "patient reminders",          "online booking"        ],        "customer_types": [          "B2B"        ],        "customer_segments": [          "smb"        ],        "compliance": [          "HIPAA"        ],        "technologies": [          "stripe",          "aws",          "intercom"        ],        "vendors": [          "aws",          "stripe"        ],        "employees": "11-50",        "employee_count": 38,        "revenue": "1m-10m",        "location": {          "country_code": "US",          "country": "United States",          "state": "Colorado",          "city": "Denver"        },        "office_locations": [          {            "country_code": "US",            "country": "United States",            "state": "Colorado",            "city": "Denver",            "employee_count": 38          }        ],        "parent": null,        "subsidiaries": [],        "socials": {          "linkedin_url": "https://www.linkedin.com/company/bracehub",          "twitter_url": null,          "facebook_url": null,          "youtube_url": null,          "github_url": null        },        "open_jobs": 2,        "web": {          "traffic_rank": 402118        }      },      "match": {        "score": 0.84,        "reason": "Sells scheduling and patient messaging software to dental and orthodontic practices."      }    }  ],  "next_cursor": null,  "usage": {    "charged": {      "lookups": 0,      "discoveries": 1    },    "already_paid": 0,    "remaining": {      "lookups": 9750,      "discoveries": 1976    }  }}

Count companies POST

How many companies match a search, and how many of them would be newly charged. Optionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`, plus `min_score`, so you can check a search before you pay for it. Free. Counts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query` (the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down. Counts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.

Find similar companies POST

Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to. All search filters work on top. Results are sorted by `match.score` (similarity to the seeds). The seeds are the examples you give us. They are never returned in the results and aren't charged. Seeds we can't find are ignored; if none are found you get a 404. Costs 1 discovery per company returned that isn't already paid for this billing month. `query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.