Skip to Content
CompanySpec
API referenceDiscovery

Find similar companies

POST
/companies/similar

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.

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Request Body

application/json
  1. body

Structured company filters. 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).

companies*array<string>

Seed companies, by domain or CompanySpec id.

Items1 <= items <= 10
similarity_weight?number

Higher favours closer matches; lower favours larger, more established companies.

Range-1 <= value <= 1
Default0
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

Similar 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/similar' \  -H 'Content-Type: application/json' \  -d '{  "companies": [    "acmedental.io"  ],  "countries": [    "US",    "CA"  ],  "min_score": 0.6,  "limit": 20}'
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.82,        "reason": "Also sells practice software to independent dental practices."      }    }  ],  "next_cursor": null,  "usage": {    "charged": {      "lookups": 0,      "discoveries": 1    },    "already_paid": 0,    "remaining": {      "lookups": 9750,      "discoveries": 1976    }  }}

Search companies POST

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.

Search page summaries POST

Search inside the summaries of company web pages, optionally limited to some page types and to companies that match filters. Returns one result per company: its best-matching page. Sorted by `match.score`. Costs 1 discovery per company returned that isn't already paid for this billing month.