# API reference (/docs/api-reference)
**Base URL:** `https://api.companyspec.com/v1`
All requests use HTTPS and a [bearer API key](/docs/authentication). Request and response bodies are JSON.
Errors use [problem details](/docs/resources/errors).
| Group | What it does | Cost |
|---|---|---|
| Account | Your plan and remaining allowances | Free |
| Reference data | Valid filter values and tracked technologies | Free |
| Companies | Resolve, look up and enrich companies you name | Lookups (resolve is free) |
| Company data | Page summaries (pricing, legal, security and compliance, integrations…), technologies, headcount, recent hires, funding, news | Lookups |
| Discovery | Count, search, lookalikes, page search, vendor customers | Discoveries (count is free) |
| Job postings | A company's postings and one posting (lookups); posting search (discoveries) | Lookups / discoveries |
## Conventions [#conventions]
- Dates are `YYYY-MM-DD`. Money is in USD unless a field says otherwise (fields end in `_usd`).
- Missing values are `null` (or `[]` for lists); fields are never left out.
- Lists are paginated with `limit` and `cursor`; see [Pagination](/docs/concepts/search#pagination).
- Every endpoint that can charge returns a [usage block](/docs/concepts/billing#the-usage-block).
Download the OpenAPI spec: [companyspec.yaml](/openapi/companyspec.yaml).
# Authentication (/docs/authentication)
Send your API key in the `Authorization` header on every request:
```http
Authorization: Bearer cs_your_key_here
```
- Create, name and revoke keys in **Dashboard → API keys**. A key is shown once, when you create it.
- All keys on your account share the same allowances. Keys will also work with the [MCP server](/docs/mcp) when it launches.
- Keep keys on the server. Don't put them in browser code or public repositories.
- A missing or invalid key returns `401`. See [Errors](/docs/resources/errors).
## Keys in the docs playground [#keys-in-the-docs-playground]
When you are signed in, the API reference creates a **Docs playground** key for you, valid for one day, and fills it
into the playground. It replaces any earlier docs key. Playground requests use your allowances like any other
request, so try free endpoints (resolve, count, values) first. There's no separate test mode: the Free plan and the
free endpoints are the way to try the API. You can revoke the key at any time from the dashboard.
# Billing & usage (/docs/concepts/billing)
## Plans [#plans]
Every plan includes two monthly allowances: **lookups** and **discoveries**. No overage charges: when an
allowance is used up, requests that need it stop until your next billing month or until you upgrade.
| Plan | Price / month | Lookups | Discoveries | Requests / minute |
|---|---|---|---|---|
| Free | $0 | 50 | 10 | 60 |
| Starter | $49 | 10,000 | 2,000 | 300 |
| Growth | $99 | 25,000 | 5,000 | 450 |
| Pro | $199 | 50,000 | 10,000 | 600 |
| Scale | $799 | 250,000 | 50,000 | 1,200 |
{/* TODO(owner): prices and allowances are provisional. */}
Need more, or a data licence? Email [support@companyspec.com](mailto:support@companyspec.com).
## Lookups and discoveries [#lookups-and-discoveries]
| | **Lookup** | **Discovery** |
|---|---|---|
| What it is | You name the company (by domain or id) | We find the company for you |
| Endpoints | Get a company, enrich, page summaries, technologies, headcount, recent hires, funding, news, a company's job postings, a single job posting | Search, lookalikes, page search, vendor customers, job posting search |
| Cost | 1 per company per billing month | 1 per company per billing month |
## The once-a-month rule [#the-once-a-month-rule]
Each company is charged **at most once per billing month**: as a discovery if we found it, or as a lookup if you
named it. After that, everything about that company is free until your billing month ends:
- **The profile**, including the optional paragraphs:
- `show_icp`: what they do and who they sell to (their ideal customer profile)
- `show_pricing`: a summary of their pricing page (plans, prices, free trial)
- `show_description`: the long company description
- `show_pages`: the most useful pages on their website, with URLs
- **Page summaries**: pricing, legal (privacy, terms, subprocessors), security and compliance, integrations,
case studies, careers and the [other page types](/docs/concepts/page-types)
- **Technologies** they use, **headcount** by department, **recent hires**, **funding** and **news**
- **All of its job postings**
Requests that return nothing, or a `404`, are never charged.
## Free endpoints [#free-endpoints]
These never use an allowance: `/account`, `/values/{field}`, `/technologies`, `/technologies/{slug}`,
`/companies/resolve` and `/companies/count`. They have their own [rate limits](/docs/resources/rate-limits).
## Count, narrow, then pull [#count-narrow-then-pull]
Searches can match thousands of companies, so check the size first:
1. `POST /companies/count` with your filters (and `min_score` if you'll use one). Free. It returns `total` and
`would_charge`: how many of them you haven't paid for this billing month.
2. Add filters until the number is what you want.
3. `POST /companies/search` with the same filters and a `limit`. You pay only for the companies returned.
```json title="Example: count response"
{ "total": 84, "total_capped": false, "would_charge": 81 }
```
Counts stop at **10,000** for filter-only searches and at **1,000** when you use `semantic_query` (the most a
search can return). `total_capped: true` means there are more than `total`.
## The usage block [#the-usage-block]
Every endpoint that can charge returns what the request cost:
```json
"usage": {
"charged": { "lookups": 0, "discoveries": 23 },
"already_paid": 2,
"remaining": { "lookups": 9750, "discoveries": 1954 }
}
```
- `charged`: companies newly charged by this request.
- `already_paid`: companies in this response you had already paid for this billing month, so they cost nothing.
- `remaining`: what's left of each allowance.
Every response, including free endpoints, also has `X-Lookups-Remaining` and `X-Discoveries-Remaining` headers.
## Billing rules in detail [#billing-rules-in-detail]
**When does the month start?** On the day your plan started, and it renews monthly. `GET /account` shows the
current billing month's start and end. The free plan works the same way, from the day you signed up.
**Per account or per key?** Per account. All your API keys share the same allowances, and a company paid for with
one key is free with every other key.
**What if my allowance runs out in the middle of a request?** You get as many companies as your remaining allowance
covers, and `usage.allowance_reached` is `true`. Once an allowance is at zero, requests that need it return
`402 allowance-exhausted`.
**Can I still read companies I already paid for after my allowance runs out?** Yes. They stay free until your
billing month ends.
**Are later pages of a search charged?** Yes, for companies on them that you haven't paid for yet.
**Are lookalike seeds charged?** No. The companies you pass to `/companies/similar` as examples are not charged and
not returned.
**What if I upgrade mid-month?** Your new allowances apply straight away, and the companies you've already paid for
stay paid.
**Does the docs playground cost anything?** Requests from the playground use your allowances like any other request.
Free endpoints and companies you've already paid for cost nothing.
## Fair use [#fair-use]
A single search returns at most 1,000 results. Copying the dataset in bulk (for example, paging through every
company in a country) is not allowed without a data licence. See the [Terms](/terms).
# Companies & IDs (/docs/concepts/companies)
## Identifying a company [#identifying-a-company]
Anywhere the API takes a `company`, you can pass either:
- its **domain**, for example `acmedental.io` (recommended; `www.` and `https://` are ignored), or
- its **id**, for example `cmp_19ad3`, from any earlier response.
Only have a name? Use [`GET /companies/resolve`](/docs/api-reference/companies/resolveCompany) to get the domain.
It's free.
## The company object [#the-company-object]
These fields are always returned:
| Field | Meaning |
|---|---|
| `id`, `domain`, `name`, `website`, `logo_url` | Identity |
| `description` | One-sentence description |
| `type` | Ownership: |
| `founded_year`, `ipo_date` | When founded; IPO date for public companies |
| `industry`, `industries`, `naics_codes`, `sic_codes`, `keywords` | Classification |
| `customer_types` | Who they sell to: |
| `customer_segments` | Kinds of customers they sell to: |
| `compliance` | Certifications they claim on their website: |
| `technologies` | Technologies they use, found on their website or in their job postings |
| `vendors` | Service providers named in their subprocessor list, e.g. `aws`, `stripe` |
| `employees`, `employee_count` | Employee range () and best estimate |
| `revenue` | Annual revenue range in USD: |
| `location`, `office_locations` | HQ, and all known offices |
| `parent`, `subsidiaries` | Corporate structure |
| `socials` | LinkedIn and other social URLs |
| `open_jobs` | Number of open job postings |
| `web.traffic_rank` | Global rank of their website by traffic; lower means more traffic |
`technologies` and `vendors` use the same slugs as [`/technologies`](/docs/api-reference/reference-data/listTechnologies).
The difference is where we found them: `technologies` are tools we detected, `vendors` are providers the company
itself lists as processing its data.
### Optional paragraphs [#optional-paragraphs]
Long text is off by default. Turn it on per request (no extra cost):
| Parameter | Adds |
|---|---|
| `show_icp=true` | `icp`: what they provide, the problem they solve and who their customers likely are |
| `show_pricing=true` | `pricing`: a summary of their pricing page (plans, prices, free trial) |
| `show_description=true` | `long_description`: the long company description |
| `show_pages=true` | `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with [`GET /companies/{company}/pages/{page_type}`](/docs/api-reference/company-data/getCompanyPage) |
`icp` and `pricing` are AI-written from the company's website. See [Where the data comes from](/docs/concepts/data).
### Detailed data [#detailed-data]
Larger datasets have their own endpoints. They're free once the company is paid for this billing month:
- [Page summaries](/docs/api-reference/company-data/getCompanyPage): pricing, legal, security and compliance,
integrations, careers and more
- [Technologies](/docs/api-reference/company-data/getCompanyTechnologies), with where and when each was found
- [Headcount](/docs/api-reference/company-data/getCompanyHeadcount) by department, with 12 months of history
- [Recent hires](/docs/api-reference/company-data/getCompanyHires) by department and seniority
- [Funding](/docs/api-reference/company-data/getCompanyFunding) and [news](/docs/api-reference/company-data/getCompanyNews)
- [Job postings](/docs/api-reference/job-postings/listCompanyJobPostings)
# Where the data comes from (/docs/concepts/data)
## Sources [#sources]
combines two sources:
- **Company websites.** We crawl each company's website, classify its pages (pricing, legal, careers and
[more](/docs/concepts/page-types)) and summarise them. This is where the ICP, pricing summary, page summaries,
compliance claims, subprocessors (`vendors`) and website technologies come from.
- **Our own company data.** Firmographics (industry, size, revenue, locations), headcount by department, recent
hires, funding, news and job postings.
## Coverage [#coverage]
About 20 million companies, with website page summaries for more than 5 million of them. Not every company has
every field or page; see [Unavailable data](/docs/concepts/unavailable-data).
{/* TODO(owner): confirm coverage numbers before launch. */}
## Freshness [#freshness]
Data is refreshed periodically.
- **Recent hires** usually appear 1–3 weeks after their start date.
- **Headcount** history covers the last 12 months.
- **Job postings** stay available after they close, with `closed_on` set.
- **Technologies** show when each was first seen and, if removed, when.
- **News events** have a `date` and a `url` to the source.
## AI-written fields [#ai-written-fields]
These are written by an AI model from the company's own website, so treat them as summaries, not quotes:
| Field | Written from |
|---|---|
| `icp` | Their website: what they provide, the problem they solve, who their customers likely are |
| `pricing` | Their pricing page |
| Page summaries (`/pages/{page_type}`) | That page; the response includes the page URL so you can check it |
| `match.reason` in search | The company's ICP compared with your `semantic_query` |
| `explanation` on technologies | What we detected and where |
Everything else is structured data.
# Page types (/docs/concepts/page-types)
We classify pages on each company's website and write a short AI summary of each page type. Where a company has
several pages of one type (for example privacy policy, terms and subprocessor list under `legal`), the summary covers
the main one and the response gives its URL.
| `page_type` | What it usually contains |
|---|---|
| `home` | What the company does, headline value proposition |
| `pricing` | Plans, prices, trials, billing model |
| `about` | History, mission, team, locations |
| `careers` | Hiring, culture, benefits |
| `blog` | Recent topics and announcements |
| `legal` | Privacy policy, terms, data processing, subprocessors |
| `integrations` | Tools and platforms they integrate with |
| `case_studies` | Customers and use cases |
| `login` | Product sign-in, often revealing SSO and auth providers |
| `status` | Status page and incident history |
| `engineering` | Engineering blog and technical stack |
| `support` | Help centre and support channels |
| `cart` | Online store / checkout |
| `compliance` | Security and compliance: trust centre, certifications |
Example (`pricing`):
```json
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
}
```
Summaries are usually two to five sentences.
Use them to:
- fetch one summary: [`GET /companies/{company}/pages/{page_type}`](/docs/api-reference/company-data/getCompanyPage)
- list what a company has: `show_pages=true` on the company profile
- filter companies that have certain pages: `page_types` in search
- search inside summaries: [`POST /pages/search`](/docs/api-reference/discovery/searchPages), for example pricing pages that mention a free trial
Not every company has every page. See [Unavailable data](/docs/concepts/unavailable-data).
# Recent hires (/docs/concepts/recent-hires)
We track people who recently joined each company, by **department**, **seniority** and **start date**.
No names or personal details are returned. New hires usually appear 1–3 weeks after their start date.
## What we track [#what-we-track]
- **Departments**:
- **Seniorities**:
- **Start date** of each hire.
## Get a company's recent hires [#get-a-companys-recent-hires]
```bash
curl "https://api.companyspec.com/v1/companies/acmedental.io/hires?within_days=90" \
-H "Authorization: Bearer $COMPANYSPEC_API_KEY"
```
You get totals by department and seniority, plus the list of hires. See
[`GET /companies/{company}/hires`](/docs/api-reference/company-data/getCompanyHires).
## Find companies by recent hires [#find-companies-by-recent-hires]
Use `recent_hires` in [search](/docs/concepts/search). For example, companies that hired at least two senior
salespeople in the last 90 days:
```json
{
"recent_hires": {
"departments": ["sales"],
"seniorities": ["senior", "director", "executive"],
"within_days": 90,
"min_count": 2
}
}
```
`within_days` can be 1–365 (default 90). Combine `recent_hires` with any other filter, for example
`customer_types: ["B2B"]` and `employees: ["51-200"]`.
Hire departments are close to, but not the same list as, headcount departments (`/values/workforce_departments`)
and job posting functions (`/values/job_functions`). Check each list before filtering.
# Search & filters (/docs/concepts/search)
`POST /companies/search` and `POST /companies/count` take these filters directly. `POST /companies/similar` takes
them too, except `query` and `semantic_query` (the seed companies describe what you want). `POST /pages/search`,
`POST /job-postings/search` and `POST /vendors/{vendor}/customers` take them inside a `company` object.
## How filters combine [#how-filters-combine]
- **Different filters** are combined with **AND**. `countries: ["US"]` plus `employees: ["11-50"]` means US
companies with 11–50 employees.
- **Values inside one list** match if the company has **any** of them. `countries: ["US", "CA"]` means US or Canada.
- **Lists with an `*_operator`** (`keywords`, `customer_types`, `customer_segments`, `compliance`, `technologies`,
`vendors`) default to **all**: `compliance: ["SOC 2", "HIPAA"]` means companies that claim both. Set
`compliance_operator: "or"` for either.
- `page_types` always means the company has all of the listed pages.
## Filters [#filters]
Get the valid values for most filters from [`GET /values/{field}`](/docs/api-reference/reference-data/listValues)
(free), using the field name in the right-hand column.
| Filter | What it matches | Values |
|---|---|---|
| `query` | Company name or domain contains this text | Any text |
| `semantic_query` | Plain-language description of what they do and who they sell to. See [Semantic search](/docs/concepts/semantic-search) | Any text, up to 500 characters |
| `countries` | HQ country | ISO codes, e.g. `US`, `GB` (`/values/countries`) |
| `states`, `cities` | HQ state or city | `/values/states`, `/values/cities` |
| `regions` | HQ region | |
| `office_locations` | Any office, not just HQ | Cities or country codes |
| `type` | Ownership type | |
| `employees` | Employee range | |
| `revenue` | Annual revenue (USD) | |
| `founded_year` | Year founded | `{ "min": 2015, "max": 2022 }` |
| `industries` | Industry | `/values/industries` |
| `naics_codes`, `sic_codes` | Industry codes; shorter NAICS codes include everything beneath them | `/values/naics_codes`, `/values/sic_codes` |
| `keywords` | Keywords on the company profile | Any text |
| `customer_types` | Who they sell to | |
| `customer_segments` | Kinds of customers they sell to | |
| `compliance` | Certifications they claim on their website | |
| `technologies` | Technologies they use; `technology_source` sets where it was found () | Slugs from [`/technologies`](/docs/api-reference/reference-data/listTechnologies) |
| `vendors` | Service providers named in their subprocessor list | Slugs from `/technologies`, e.g. `aws` |
| `page_types` | Has these pages on their website | ([what each is](/docs/concepts/page-types)) |
| `funding_rounds` | Has raised these round types | |
| `funding_amount` | Total funding (USD) | `{ "min": 1000000 }` |
| `funding_year` | Year of most recent round | `{ "min": 2024 }` |
| `investors` | Backed by these investors | Names or domains |
| `workforce_size` | Headcount in a department | `[{ "department": "engineering", "min": 20 }]`. Departments: |
| `workforce_growth` | Headcount growth | `{ "period": "y1", "min_percent": 20 }`. Periods: (6 months, 1 year, 2 years) |
| `recent_hires` | Recently hired people. See [Recent hires](/docs/concepts/recent-hires) | `{ "departments": ["sales"], "within_days": 90, "min_count": 2 }`. Departments: . Seniorities: |
| `hiring` | Has open job postings | `{ "job_functions": ["sales"], "posted_within_days": 30 }`. Functions: . Seniorities: |
| `news` | Has recent news | `{ "categories": ["launches"], "within_days": 90 }`. Categories: |
| `require` | Has this data | |
| `exclude` | Remove companies matching any of these | `{ "domains": ["acme.com"], "employees": ["1-10"] }` |
## Example [#example]
```json
{
"semantic_query": "practice management software for independent dental practices",
"countries": ["US"],
"employees": ["11-50", "51-200"],
"customer_types": ["B2B"],
"compliance": ["HIPAA"],
"recent_hires": { "departments": ["sales"], "within_days": 90 },
"exclude": { "domains": ["acmedental.io"] },
"limit": 25
}
```
## Order of results [#order-of-results]
- With `semantic_query`: by `match.score`, highest first. `semantic_weight` (0–1, default `0.7`) sets how much
relevance counts against company size and web traffic.
- Without it: larger companies with more web traffic first.
## Pagination [#pagination]
`limit` is 1–100 per page (default 25). Responses include `next_cursor`; pass it as `cursor` to get the next page. A cursor is valid for 24 hours.
A search returns at most 1,000 results in total; narrow your filters if you need different ones. Each new company on
a later page is charged like the first page.
## Pricing information [#pricing-information]
Pricing is stored as a paragraph, so there is no price filter. To find companies by pricing details, search inside
pricing pages with [`POST /pages/search`](/docs/api-reference/discovery/searchPages) and `page_types: ["pricing"]`.
# Semantic search (/docs/concepts/semantic-search)
Put a description in `semantic_query` and we match it against what each company does **and** who it sells to.
```json
{ "semantic_query": "practice management software for independent dental practices" }
```
## Writing good queries [#writing-good-queries]
- **Say who the customers are.** "Software for independent dental practices" finds vendors that sell to dental
practices, not the practices themselves.
- **Name the product.** "Practice management software" is better than "software".
- **Keep hard constraints in filters.** Country, size, `customer_types` and `customer_segments` work as strict
yes/no filters; put them in filters rather than in the sentence.
- **One idea per query.** For two different products, run two searches.
## Scores [#scores]
Each result includes `match.score` (0–1) and a short AI-written `match.reason` explaining the match. Results are
sorted by score.
- **Above 0.8:** strong matches.
- **0.6–0.8:** usually relevant; check the reason.
- **Below 0.6:** loosely related.
Use `min_score` to drop weaker matches. Even without it, very weak matches are never returned, so a search for
something rare returns few results rather than unrelated companies. Pass the same `min_score` to `/companies/count`
to see how many you'll get; semantic counts stop at 1,000 (`total_capped: true` means there are more).
## Weighting [#weighting]
`semantic_weight` (0–1, default `0.7`) balances relevance against company size and web traffic. Lower it to favour
larger, better-known companies among good matches.
# Unavailable data (/docs/concepts/unavailable-data)
Company websites differ a lot, so some data is missing for some companies. Data is refreshed periodically.
| Case | What you get | Charged? |
|---|---|---|
| A field has no value | `null` or an empty array | Yes, as usual (1 lookup if not already paid) |
| An optional paragraph (`icp`, `pricing`, `long_description`) doesn't exist | The field is `null` | Yes, as usual |
| A page type isn't available | `404 page-not-available` with `available_page_types` | No |
| The company isn't found | `404 not-found` | No |
Example:
```json
{
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a pricing page for acmedental.io.",
"available_page_types": ["home", "about", "legal", "careers"]
}
```
To only get companies that have certain data, use `require` (for example `"require": ["icp", "pricing_page"]`) or
`page_types` in [search](/docs/concepts/search). Coverage and freshness are on [Where the data comes from](/docs/concepts/data).
# Introduction (/docs)
turns company websites into structured data you can search and look up by API
(an [MCP server](/docs/mcp) is coming soon).
For each company you get what they do, who they sell to, their technologies and vendors, compliance claims,
hiring, recent hires, funding and news, plus summaries of key pages like pricing, legal and careers.
## What you can do [#what-you-can-do]
"Practice management software for independent dental practices." One query, filters on top.
Basic profile by domain, with optional paragraphs for ICP, pricing and description.
Up to 10 seed companies in, similar companies out, with a similarity score.
Open job postings and recent hires by department and seniority.
## How billing works [#how-billing-works]
Each company costs at most once a month: one **lookup** if you name it, or one **discovery** if we find it for you.
After that, everything about it is free for the rest of the month: its ICP (who they sell to), pricing summary,
page summaries, technologies, headcount, recent hires, funding, news and job postings. [Read more](/docs/concepts/billing).
## Next steps [#next-steps]
### Get an API key [#get-an-api-key]
[Create a free account](/sign-up) (50 lookups and 10 discoveries a month) and copy a key from the dashboard.
[See all plans](/docs/concepts/billing#plans).
### Make your first call [#make-your-first-call]
Follow the [Quickstart](/docs/quickstart).
### Explore the API reference [#explore-the-api-reference]
Every endpoint has a playground. Signed in, your key is filled in for you.
These docs are available as Markdown: add `.md` to any page URL, or fetch [/llms.txt](/llms.txt) and
[/llms-full.txt](/llms-full.txt).
# MCP server (/docs/mcp)
The MCP server is in development. Until it ships, agents can call the REST API directly.
## What to expect [#what-to-expect]
- A remote server you add to your MCP client with a URL, signing in with your account or an API key.
- Tools for resolving, looking up, searching and finding lookalikes, plus page summaries and job postings.
- The same plans and billing as the REST API: one charge per company per billing month, and free counts.
Until then, see [Research companies with an AI agent](/docs/recipes/agent-workflow).
# Quickstart (/docs/quickstart)
### Create an API key [#create-an-api-key]
[Sign up](/sign-up), then open [Dashboard → API keys](/dashboard/api-keys) and create a key. It is shown once, so copy it.
```bash
export COMPANYSPEC_API_KEY="cs_..."
```
### Look up a company [#look-up-a-company]
```bash tab="cURL"
curl "https://api.companyspec.com/v1/companies/stripe.com?show_icp=true" \
-H "Authorization: Bearer $COMPANYSPEC_API_KEY"
```
```python tab="Python"
import os, requests
r = requests.get(
"https://api.companyspec.com/v1/companies/stripe.com",
params={"show_icp": "true"},
headers={"Authorization": f"Bearer {os.environ['COMPANYSPEC_API_KEY']}"},
)
print(r.json()["company"]["icp"])
```
```ts tab="TypeScript"
const res = await fetch('https://api.companyspec.com/v1/companies/stripe.com?show_icp=true', {
headers: { Authorization: `Bearer ${process.env.COMPANYSPEC_API_KEY}` },
});
const { company, usage } = await res.json();
```
Response (shortened):
```json
{
"company": {
"id": "cmp_8f2k1",
"domain": "stripe.com",
"name": "Stripe",
"customer_types": ["B2B"],
"customer_segments": ["smb", "enterprise"],
"employees": "5K-10K",
"icp": "Stripe provides payments infrastructure for businesses that sell online ... Their customers are likely ..."
},
"usage": {
"charged": { "lookups": 1, "discoveries": 0 },
"already_paid": 0,
"remaining": { "lookups": 49, "discoveries": 10 }
}
}
```
This costs 1 lookup. Looking up Stripe again during your billing month is free.
### Find companies [#find-companies]
Count first. It's free, so you can check how many companies match before paying for any:
```bash
curl https://api.companyspec.com/v1/companies/count \
-H "Authorization: Bearer $COMPANYSPEC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"semantic_query": "practice management software for independent dental practices", "countries": ["US"], "min_score": 0.6}'
```
```json
{ "total": 84, "total_capped": false, "would_charge": 84 }
```
84 is a reasonable number, so get the first 25:
```bash
curl https://api.companyspec.com/v1/companies/search \
-H "Authorization: Bearer $COMPANYSPEC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"semantic_query": "practice management software for independent dental practices", "countries": ["US"], "min_score": 0.6, "limit": 25}'
```
Each result has the company and a `match` with its `score` and a short `reason`.
Each company returned costs 1 discovery unless you already paid for it this billing month. After that, everything else
about it is free until the month ends: its ICP (who they sell to), pricing summary, page summaries, technologies,
headcount, recent hires, funding, news and job postings.
Every response includes a `usage` block showing what the request cost and what you have left.
# Research companies with an AI agent (/docs/recipes/agent-workflow)
Agents work best when they start broad and free, then go deep only on companies that matter.
1. **Understand the question.** Turn "who sells scheduling software to dentists in Texas?" into filters plus a
`semantic_query`. Use `GET /values/{field}` to check valid filter values.
2. **Count first.** `POST /companies/count` is free (30 per minute). If the total is large, add filters before searching.
3. **Search with a small limit.** Start with `limit: 10–25` and `min_score`.
4. **Go deep on the shortlist.** Profiles, page summaries (`/companies/{company}/pages/pricing`,
`/companies/{company}/pages/legal`), technologies and job postings are free for companies already returned this
billing month.
5. **Cite the source page.** Page summaries include the page URL, so the agent can show where a claim came from.
## Example prompt for your agent [#example-prompt-for-your-agent]
```text
You have the CompanySpec API. Call /companies/count before /companies/search (max 30 counts per minute).
Never request more than 25 results unless the user asks. Use page summaries to
answer questions about pricing, security or integrations, and include the page URL.
```
## Tool definitions [#tool-definitions]
To give an agent these endpoints as tools (function calling), generate the tool schemas from the
[OpenAPI spec](/openapi/companyspec.yaml). Start with resolve, count, search, get a company and get a page summary;
that covers most questions.
An official MCP server is on the way. See [MCP](/docs/mcp).
# Enrich your CRM (/docs/recipes/enrich-crm)
Send up to 100 companies per request to `POST /companies/enrich`. Use domains when you have them.
```bash
curl https://api.companyspec.com/v1/companies/enrich \
-H "Authorization: Bearer $COMPANYSPEC_API_KEY" -H "Content-Type: application/json" \
-d '{
"companies": ["stripe.com", "linear.app", "notarealdomain.xyz"],
"show_icp": true
}'
```
Companies we can't find are listed in `not_found` and aren't charged:
```json
{
"companies": [
{ "domain": "stripe.com", "name": "Stripe", "icp": "..." },
{ "domain": "linear.app", "name": "Linear", "icp": "..." }
],
"not_found": ["notarealdomain.xyz"],
"usage": { "charged": { "lookups": 2, "discoveries": 0 }, "already_paid": 0, "remaining": { "lookups": 9748, "discoveries": 2000 } }
}
```
## Only have names? [#only-have-names]
Resolve them first with [`GET /companies/resolve`](/docs/api-reference/companies/resolveCompany) (free), passing
`country` or `linkedin_url` when you have them, then enrich by domain:
```python
import os, requests
API = "https://api.companyspec.com/v1"
H = {"Authorization": f"Bearer {os.environ['COMPANYSPEC_API_KEY']}"}
domains, unsure = [], []
for name, country in [("Mercury", "US"), ("Acme Dental", "US")]:
r = requests.get(f"{API}/companies/resolve", params={"name": name, "country": country}, headers=H).json()
m = r["match"]
if m and m["confidence"] >= 0.8:
domains.append(m["domain"])
else:
unsure.append((name, r)) # review these by hand
enriched = requests.post(f"{API}/companies/enrich", json={"companies": domains, "show_icp": True}, headers=H).json()
```
Store the `id` from each result in your CRM so later lookups don't depend on the domain.
## Re-running every month [#re-running-every-month]
Each company costs 1 lookup per billing month no matter how many times you request it, so it's safe to retry failed batches
or enrich the same account from several workflows.
# Use hiring signals (/docs/recipes/hiring-signals)
Two kinds of signal are available:
- **Open job postings**: what a company plans to do.
- **Recent hires**: who just joined, by department and seniority. See [Recent hires](/docs/concepts/recent-hires).
## Companies hiring for a role [#companies-hiring-for-a-role]
Search postings directly. Results are grouped by company and include the matching postings. You pay 1 discovery
per company, however many of its postings match.
```bash
curl https://api.companyspec.com/v1/job-postings/search \
-H "Authorization: Bearer $COMPANYSPEC_API_KEY" -H "Content-Type: application/json" \
-d '{
"title": "revenue operations",
"posted_within_days": 30,
"company": { "countries": ["US"], "employees": ["51-200", "201-500"] },
"limit": 25
}'
```
## Companies that just built a team [#companies-that-just-built-a-team]
```json
{
"customer_types": ["B2B"],
"recent_hires": { "departments": ["engineering"], "seniorities": ["director", "executive"], "within_days": 90 }
}
```
Send this to `POST /companies/search` to find B2B companies that hired an engineering leader in the last 90 days.
New leaders often review tools and vendors in their first months.
## A company's postings [#a-companys-postings]
`GET /companies/{company}/job-postings` costs 1 lookup per company per billing month and returns all of its open
postings. Add `status=closed` or `status=all` to include postings that have closed, for example to see what a
company was hiring for earlier in the year. Job posting search takes the same `status` option.
# Find companies by who they sell to (/docs/recipes/icp-search)
Goal: US vendors of practice management software for independent dental practices, 11–200 employees.
### Count (free) [#count-free]
```bash
curl https://api.companyspec.com/v1/companies/count \
-H "Authorization: Bearer $COMPANYSPEC_API_KEY" -H "Content-Type: application/json" \
-d '{
"semantic_query": "practice management software for independent dental practices",
"countries": ["US"],
"employees": ["11-50", "51-200"],
"min_score": 0.6
}'
```
```json
{ "total": 57, "total_capped": false, "would_charge": 57 }
```
Pass the same `min_score` you'll use in the search, so the count matches what you'll pay for.
### Narrow if needed [#narrow-if-needed]
Add filters until the list is the right size. For example, only companies that list HIPAA and are hiring in sales:
```json
{ "compliance": ["HIPAA"], "hiring": { "job_functions": ["sales"] } }
```
Add `"group_by": ["customer_segments"]` to the count to see how the matches split. Up to 3 fields; see
[Count companies](/docs/api-reference/discovery/countCompanies) for the list.
### Pull the results [#pull-the-results]
```bash
curl https://api.companyspec.com/v1/companies/search \
-H "Authorization: Bearer $COMPANYSPEC_API_KEY" -H "Content-Type: application/json" \
-d '{
"semantic_query": "practice management software for independent dental practices",
"countries": ["US"],
"employees": ["11-50", "51-200"],
"min_score": 0.6,
"limit": 50
}'
```
Results are sorted by `match.score`, highest first. You pay 1 discovery per company returned, once per billing
month. With 57 matches and `limit: 50`, pass the `next_cursor` from the response as `cursor` to get the last 7.
### Read the details (free for the rest of the billing month) [#read-the-details-free-for-the-rest-of-the-billing-month]
Every company in the results is now paid for this billing month, so everything else about it is free until the
month ends: its profile with ICP (`show_icp=true`) and pricing summary (`show_pricing=true`), page summaries, technologies,
headcount, recent hires, funding, news and job postings.
# Find lookalike companies (/docs/recipes/lookalikes)
Pass up to 10 **seed** companies: examples of the kind of company you want, such as your best customers. We combine
what they do and who they sell to, then return similar companies.
```bash
curl https://api.companyspec.com/v1/companies/similar \
-H "Authorization: Bearer $COMPANYSPEC_API_KEY" -H "Content-Type: application/json" \
-d '{
"companies": ["acmedental.io", "brightsmile-software.com"],
"countries": ["US", "CA"],
"exclude": { "domains": ["already-a-customer.com"] },
"limit": 25
}'
```
- All [search filters](/docs/concepts/search) work on top of the seeds, except `query` and `semantic_query`: the
seeds already describe what you're looking for.
- Seeds are never returned in the results, and they aren't charged.
- Results are sorted by `match.score`, their similarity to the seeds. `min_score` drops weaker ones.
- `similarity_weight` (`-1` to `1`, default `0`): at `1`, only closeness to the seeds counts; at `-1`, larger,
better-known companies are pushed up among the matches.
- Returned companies cost 1 discovery each, once per billing month.
- Seeds we can't find are ignored. If none are found, you get a `404`.
Pick seeds that are similar to each other. Seeds from different markets give blended, weaker results; run one
request per market instead.
# Changelog (/docs/resources/changelog)
## v1 preview (November 2026) [#v1-preview-november-2026]
- First public version: companies, company data, discovery, job postings and reference data.
- Once-a-month billing per company, with separate lookup and discovery allowances.
**What "preview" means:** field names and endpoints may still change before v1 is marked stable. Every change will be
listed here. After that, breaking changes only happen in a new version (`/v2`), and v1 keeps working.
# Errors (/docs/resources/errors)
Errors return `Content-Type: application/problem+json` in the standard
[problem details](https://www.rfc-editor.org/rfc/rfc9457) format:
```json
{
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [{ "field": "employees[0]", "message": "Unknown value '10-50'" }],
"request_id": "req_01JC8X4T2M"
}
```
- `type`: identifies the error; match on the last part (`validation-error`).
- `detail`: a human-readable explanation.
- `errors`: only on `422`, one entry per invalid field.
- `available_page_types`: only on `page-not-available`.
- `request_id`: include it when you contact support.
| Status | `type` | When | Charged? |
|---|---|---|---|
| 400 | `bad-request` | The body isn't valid JSON, or a parameter has the wrong type | No |
| 401 | `unauthorized` | Missing, invalid or revoked API key | No |
| 402 | `allowance-exhausted` | The allowance this request needs (named in `detail`) is at zero | No |
| 403 | `forbidden` | Your account is suspended (for example for bulk copying, see Fair use) | No |
| 404 | `not-found` | The company or resource doesn't exist | No |
| 404 | `page-not-available` | We don't have that page type for the company | No |
| 422 | `validation-error` | Valid JSON, but a value isn't allowed (unknown filter value, out of range) | No |
| 429 | `rate-limited` | Too many requests. Wait for `Retry-After` seconds | No |
| 500 | `internal-error` | Our fault. Retry with backoff | No |
Example `402`:
```json
{
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
```
Questions? Email [support@companyspec.com](mailto:support@companyspec.com) with the `request_id`.
{/* TODO(owner): confirm support address. */}
# Rate limits (/docs/resources/rate-limits)
| Plan | Requests / minute | Requests at the same time |
|---|---|---|
| Free | 60 | 2 |
| Starter | 300 | 20 |
| Growth | 450 | 30 |
| Pro | 600 | 40 |
| Scale | 1,200 | 60 |
{/* TODO(owner): confirm limits before launch. */}
Free endpoints count towards your plan's per-minute limit. Two of them also have their own, lower limits on every plan:
| Endpoint | Limit |
|---|---|
| `POST /companies/count` | 30 per minute; 500 per day on the Free plan |
| `GET /companies/resolve` | 60 per minute |
Every response includes these headers:
- `RateLimit-Limit`: requests allowed per minute
- `RateLimit-Remaining`: requests left in the current minute
- `RateLimit-Reset`: seconds until the minute resets
- `X-Lookups-Remaining`, `X-Discoveries-Remaining`: what's left of your allowances
Going over any limit, including too many requests at the same time, returns `429 rate-limited` with a `Retry-After`
header in seconds. Wait that long, then retry with exponential backoff.
Rate limits are separate from allowances. Running out of an allowance returns `402`, not `429`.
# Get account and usage (/docs/api-reference/account/getAccount)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# List filter values (/docs/api-reference/reference-data/listValues)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# List technologies (/docs/api-reference/reference-data/listTechnologies)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Get a technology (/docs/api-reference/reference-data/getTechnology)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Resolve a company (/docs/api-reference/companies/resolveCompany)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Get a company (/docs/api-reference/companies/getCompany)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Enrich companies in bulk (/docs/api-reference/companies/enrichCompanies)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Get a page summary (/docs/api-reference/company-data/getCompanyPage)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Get technologies (/docs/api-reference/company-data/getCompanyTechnologies)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Get headcount (/docs/api-reference/company-data/getCompanyHeadcount)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Get recent hires (/docs/api-reference/company-data/getCompanyHires)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Get funding (/docs/api-reference/company-data/getCompanyFunding)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Get news events (/docs/api-reference/company-data/getCompanyNews)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Count companies (/docs/api-reference/discovery/countCompanies)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Search companies (/docs/api-reference/discovery/searchCompanies)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Find similar companies (/docs/api-reference/discovery/findSimilarCompanies)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Search page summaries (/docs/api-reference/discovery/searchPages)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# List a vendor's customers (/docs/api-reference/discovery/listVendorCustomers)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# List a company's job postings (/docs/api-reference/job-postings/listCompanyJobPostings)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Get a job posting (/docs/api-reference/job-postings/getJobPosting)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```
# Search job postings (/docs/api-reference/job-postings/searchJobPostings)
```json
{
"openapi": "3.2.0",
"info": {
"title": "CompanySpec API",
"version": "1.0.0",
"description": "Company data from what every company says about itself: who they sell to, what they do,\ntheir technologies, vendors, compliance claims, hiring, funding and more.\n\n**Billing.** Each company is charged at most once per billing month:\none *lookup* when you name it, or one *discovery* when we find it for you.\nAfter that, everything about that company is free for the rest of your billing month: its profile with\nICP (what they do and who they sell to), pricing summary, long description and list of most useful pages;\nits page summaries (pricing, legal, security and compliance, integrations and more); technologies;\nheadcount; recent hires; funding; news; and all of its job postings.\nAllowances belong to your account and are shared by all its API keys.\nUnavailable data (404) is never charged.\n",
"license": {
"name": "Proprietary",
"url": "https://companyspec.com/terms"
}
},
"servers": [
{
"url": "https://api.companyspec.com/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Account",
"description": "Your plan, limits and usage."
},
{
"name": "Reference data",
"description": "Valid filter values and the technologies we track. Always free."
},
{
"name": "Companies",
"description": "Resolve, look up and enrich companies you already know."
},
{
"name": "Company data",
"description": "Detailed data for one company: page summaries (pricing, legal, security and compliance, integrations and more),\ntechnologies, headcount, recent hires, funding and news. Free once the company is paid for this billing month."
},
{
"name": "Discovery",
"description": "Find companies you don't know yet. Charged as discoveries."
},
{
"name": "Job postings",
"description": "Job postings by company or across all companies."
}
],
"paths": {
"/account": {
"get": {
"operationId": "getAccount",
"tags": [
"Account"
],
"summary": "Get account and usage",
"description": "Your plan, your current billing month and how much of each allowance you have used. Free.",
"responses": {
"200": {
"description": "Account details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"plan": "starter",
"period": {
"start": "2026-11-03",
"end": "2026-12-02"
},
"lookups": {
"used": 250,
"limit": 10000
},
"discoveries": {
"used": 23,
"limit": 2000
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/values/{field}": {
"get": {
"operationId": "listValues",
"tags": [
"Reference data"
],
"summary": "List filter values",
"description": "Valid values for a filter, with the number of companies that have each value (across all companies).\nUse these values in `/companies/search`, `/companies/count`, `/companies/similar`, `/pages/search` and\n`/job-postings/search`. Free.\n",
"parameters": [
{
"name": "field",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ValueField"
},
"example": "industries"
},
{
"name": "q",
"in": "query",
"description": "Only return values that contain this text.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "dent"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Values for the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValuesResponse"
},
"example": {
"field": "industries",
"values": [
{
"value": "Dentists",
"label": "Dentists",
"companies": 141203
},
{
"value": "Dental Equipment Manufacturing",
"label": "Dental Equipment Manufacturing",
"companies": 3112
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/technologies": {
"get": {
"operationId": "listTechnologies",
"tags": [
"Reference data"
],
"summary": "List technologies",
"description": "Every technology and service provider we track: tools found on company websites and in job postings, and providers named in subprocessor lists. Includes how many companies use each. Free.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search by name.",
"schema": {
"type": "string",
"maxLength": 100
},
"example": "stripe"
},
{
"name": "category",
"in": "query",
"description": "A technology category from `/values/technology_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"companies",
"name"
],
"default": "companies"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"next_cursor"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TechnologySummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"companies": 184230
},
{
"slug": "stripe-billing",
"name": "Stripe Billing",
"categories": [
"Subscription billing"
],
"companies": 21704
}
],
"next_cursor": null
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/technologies/{slug}": {
"get": {
"operationId": "getTechnology",
"tags": [
"Reference data"
],
"summary": "Get a technology",
"description": "Profile of one technology: who makes it, its categories and the tools it integrates with. Free.",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "stripe",
"description": "A slug from `/technologies`."
}
],
"responses": {
"200": {
"description": "Technology profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TechnologyProfile"
},
"example": {
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"tags": [
"payments",
"billing",
"api"
],
"pricing_models": [
"usage_based"
],
"license_types": [
"commercial"
],
"github_repo": null,
"companies": 184230,
"integrates_with": [
"shopify",
"quickbooks",
"hubspot"
],
"made_by": {
"name": "Stripe",
"domain": "stripe.com"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/resolve": {
"get": {
"operationId": "resolveCompany",
"tags": [
"Companies"
],
"summary": "Resolve a company",
"description": "Turn a name, domain or LinkedIn URL into a company. Returns the best match and, if you ask\nfor them with `limit`, up to 4 alternatives (fewer if there aren't that many good candidates).\nUse it to get the domain to pass to other endpoints. Provide at least one of `name`, `domain` or `linkedin_url`.\n\n`confidence` (0–1) says how sure we are. Above 0.8 is usually right; below 0.5, check the alternatives.\n`match` is `null` when nothing is close enough.\n\nFree. Limited to 60 requests per minute.\n",
"parameters": [
{
"name": "name",
"in": "query",
"schema": {
"type": "string",
"maxLength": 250
},
"example": "Mercury"
},
{
"name": "domain",
"in": "query",
"schema": {
"type": "string",
"maxLength": 253
}
},
{
"name": "linkedin_url",
"in": "query",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "country",
"in": "query",
"description": "ISO 3166-1 alpha-2 country code to prefer.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "US"
},
{
"name": "limit",
"in": "query",
"description": "Total candidates to return, including the best match.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1
},
"example": 3
}
],
"responses": {
"200": {
"description": "Best match and alternatives.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveResponse"
},
"example": {
"match": {
"id": "cmp_5m0q2",
"domain": "mercury.com",
"name": "Mercury",
"logo_url": "https://logos.companyspec.com/mercury.com.png",
"confidence": 0.91
},
"alternatives": [
{
"id": "cmp_9w3ns",
"domain": "mercuryinsurance.com",
"name": "Mercury Insurance",
"logo_url": null,
"confidence": 0.62
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/{company}": {
"get": {
"operationId": "getCompany",
"tags": [
"Companies"
],
"summary": "Get a company",
"description": "Basic company information is always returned. Long paragraphs are off by default; turn them on with\n`show_icp=true` (what they do and who they sell to), `show_pricing=true` (pricing page summary),\n`show_description=true` (long description) and `show_pages=true` (the most useful pages on their website, with URLs).\nCosts 1 lookup, free if the company is already paid for this billing month. Field meanings are on the Companies & IDs page.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"$ref": "#/components/parameters/ShowIcp"
},
{
"$ref": "#/components/parameters/ShowPricing"
},
{
"$ref": "#/components/parameters/ShowDescription"
},
{
"$ref": "#/components/parameters/ShowPages"
}
],
"responses": {
"200": {
"description": "The company.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"usage"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US.",
"pricing": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans.",
"pages": [
{
"page_type": "home",
"url": "https://acmedental.io"
},
{
"page_type": "pricing",
"url": "https://acmedental.io/pricing"
},
{
"page_type": "legal",
"url": "https://acmedental.io/privacy"
}
]
},
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/enrich": {
"post": {
"operationId": "enrichCompanies",
"tags": [
"Companies"
],
"summary": "Enrich companies in bulk",
"description": "Look up to 100 companies in one call, by domain or id (you can mix them). Accepts the same options as\n`GET /companies/{company}`: `show_icp`, `show_pricing`, `show_description` and `show_pages`.\nResults come back in the order you sent them; duplicates are returned once.\nCosts 1 lookup per company found that isn't already paid for this billing month. Companies we can't find are\nlisted in `not_found` and aren't charged. If your allowance runs out partway, the companies it covered are returned\nand `usage.allowance_reached` is `true`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrichRequest"
},
"example": {
"companies": [
"acmedental.io",
"bracehub.com",
"not-a-real-company.example"
],
"show_icp": true
}
}
}
},
"responses": {
"200": {
"description": "Companies found and not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"companies",
"not_found",
"usage"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company"
}
},
"not_found": {
"type": "array",
"items": {
"type": "string"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"companies": [
{
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"website": "https://acmedental.io",
"description": "Practice management software for independent dental clinics.",
"logo_url": null,
"type": "private",
"founded_year": 2017,
"ipo_date": null,
"industry": "Software Development",
"industries": [
"Software Development",
"Healthcare Technology"
],
"naics_codes": [
"513210"
],
"sic_codes": [
"7372"
],
"keywords": [
"practice management",
"dental scheduling",
"patient billing"
],
"customer_types": [
"B2B"
],
"customer_segments": [
"smb"
],
"compliance": [
"HIPAA",
"SOC 2"
],
"technologies": [
"stripe",
"twilio",
"aws",
"hubspot"
],
"vendors": [
"aws",
"stripe",
"twilio"
],
"employees": "51-200",
"employee_count": 142,
"revenue": "10m-50m",
"location": {
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin"
},
"office_locations": [
{
"country_code": "US",
"country": "United States",
"state": "Texas",
"city": "Austin",
"employee_count": 120
}
],
"parent": null,
"subsidiaries": [],
"socials": {
"linkedin_url": "https://www.linkedin.com/company/acmedental",
"twitter_url": null,
"facebook_url": null,
"youtube_url": null,
"github_url": null
},
"open_jobs": 6,
"web": {
"traffic_rank": 184021
},
"icp": "AcmeDental provides cloud practice management software covering scheduling, charting and billing. They solve the pain of juggling separate tools for appointments and insurance claims. Their customers are likely independent dental practices and small multi-location groups in the US."
},
{
"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
},
"icp": "BraceHub provides online booking, reminders and two-way messaging for orthodontic and dental practices. They reduce no-shows and front-desk phone time. Their customers are likely independent orthodontists and small dental groups in the US."
}
],
"not_found": [
"not-a-real-company.example"
],
"usage": {
"charged": {
"lookups": 2,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9748,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/companies/{company}/pages/{page_type}": {
"get": {
"operationId": "getCompanyPage",
"tags": [
"Company data"
],
"summary": "Get a page summary",
"description": "The summary of one page on a company's website, with its URL. Summaries are AI-written from the page.\nCosts 1 lookup, free if the company is already paid for this billing month.\nIf we don't have that page type for the company you get a 404 that lists the page types we do have; it isn't charged.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "page_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PageType"
},
"example": "pricing",
"description": "One of the page types listed on the Page types page."
}
],
"responses": {
"200": {
"description": "The page summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page",
"usage"
],
"properties": {
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"page": {
"page_type": "pricing",
"url": "https://acmedental.io/pricing",
"summary": "Three plans billed per location per month, from $199 (Starter) to $499 (Pro), with custom pricing for groups of 10+ locations. A 30-day free trial is offered and onboarding is included on annual plans."
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"description": "Company not found, or this page type isn't available for the company.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/page-not-available",
"title": "Page not available",
"status": 404,
"detail": "We don't have a careers page for acmedental.io.",
"available_page_types": [
"home",
"pricing",
"about",
"legal",
"compliance"
],
"request_id": "req_01JC8X4T2M"
}
}
}
}
}
}
},
"/companies/{company}/technologies": {
"get": {
"operationId": "getCompanyTechnologies",
"tags": [
"Company data"
],
"summary": "Get technologies",
"description": "Every technology we have detected for the company: where we found it (`website` or `jobs`), when it was\nfirst seen and, if they stopped using it, when. `explanation` says in plain words what we found.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"removed",
"all"
],
"default": "active"
}
}
],
"responses": {
"200": {
"description": "Technologies.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"technologies",
"usage"
],
"properties": {
"technologies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyTechnology"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"technologies": [
{
"slug": "stripe",
"name": "Stripe",
"categories": [
"Payments"
],
"sources": [
"website",
"jobs"
],
"first_seen": "2024-03-01",
"removed_on": null,
"versions": [],
"explanation": "Stripe.js is loaded on the checkout page, and two backend job postings ask for Stripe API experience."
}
],
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/headcount": {
"get": {
"operationId": "getCompanyHeadcount",
"tags": [
"Company data"
],
"summary": "Get headcount",
"description": "Current headcount by department, and total headcount per month for the last 12 months.\nCosts 1 lookup, free if the company is already paid for this billing month.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Headcount.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"headcount",
"usage"
],
"properties": {
"headcount": {
"$ref": "#/components/schemas/Headcount"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"headcount": {
"employee_count": 142,
"departments": [
{
"department": "engineering",
"employee_count": 48
},
{
"department": "sales",
"employee_count": 31
}
],
"history": [
{
"month": "2026-08",
"employee_count": 131
},
{
"month": "2026-09",
"employee_count": 137
},
{
"month": "2026-10",
"employee_count": 142
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/hires": {
"get": {
"operationId": "getCompanyHires",
"tags": [
"Company data"
],
"summary": "Get recent hires",
"description": "People who recently joined the company, counted by department and seniority, plus the most recent\nhires (up to 100). Departments come from `/values/hire_departments` and seniorities from `/values/hire_seniorities`.\nNo names or personal details are returned.\nCosts 1 lookup, free if the company is already paid for this billing month.\n\nNew hires usually appear 1–3 weeks after their start date.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
}
},
{
"name": "department",
"in": "query",
"description": "A value from `/values/hire_departments`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/hire_seniorities`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recent hires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"hires",
"usage"
],
"properties": {
"hires": {
"$ref": "#/components/schemas/HiresResponse"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"hires": {
"within_days": 90,
"total": 9,
"by_department": {
"engineering": 4,
"sales": 3,
"marketing": 2
},
"by_seniority": {
"senior": 3,
"mid": 4,
"executive": 1,
"entry": 1
},
"items": [
{
"department": "sales",
"seniority": "executive",
"start_date": "2026-10-06"
},
{
"department": "engineering",
"seniority": "senior",
"start_date": "2026-09-22"
}
]
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/funding": {
"get": {
"operationId": "getCompanyFunding",
"tags": [
"Company data"
],
"summary": "Get funding",
"description": "Funding rounds, investors and acquisitions. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
}
],
"responses": {
"200": {
"description": "Funding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"funding",
"usage"
],
"properties": {
"funding": {
"$ref": "#/components/schemas/Funding"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"funding": {
"total_funding_usd": 15000000,
"rounds": [
{
"type": "series_a",
"name": "Series A",
"announced_on": "2025-04-15",
"amount_usd": 15000000,
"pre_money_valuation_usd": null,
"post_money_valuation_usd": null,
"lead_investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
]
}
],
"investors": [
{
"name": "Example Ventures",
"domain": "example.vc"
},
{
"name": "Seed Fund II",
"domain": null
}
],
"acquisitions": []
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/news": {
"get": {
"operationId": "getCompanyNews",
"tags": [
"Company data"
],
"summary": "Get news events",
"description": "Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "category",
"in": "query",
"description": "A value from `/values/news_categories`.",
"schema": {
"type": "string"
}
},
{
"name": "within_days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 730
},
"description": "Only events from the last N days. Default 365."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "News events.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"news",
"next_cursor",
"usage"
],
"properties": {
"news": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewsEvent"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"news": [
{
"id": "nws_91ad2",
"category": "launches",
"category_group": "product",
"date": "2026-09-30",
"summary": "Launched an AI scheduling assistant for dental front desks.",
"amount_usd": null,
"url": "https://acmedental.io/blog/ai-scheduling-assistant"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/count": {
"post": {
"operationId": "countCompanies",
"tags": [
"Discovery"
],
"summary": "Count companies",
"description": "How many companies match a search, and how many of them would be newly charged.\nOptionally break the total down by up to 3 fields with `group_by`. Takes the same filters as `/companies/search`,\nplus `min_score`, so you can check a search before you pay for it. Free.\n\nCounts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use `semantic_query`\n(the most a search can return). `total_capped: true` means there are more than `total`; add filters to narrow it down.\n\nCounts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"type": "object",
"properties": {
"group_by": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"countries",
"employees",
"revenue",
"type",
"customer_types",
"customer_segments",
"industries",
"compliance",
"funding_rounds"
]
},
"description": "Break the counts down by these fields (up to 3)."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Only count matches with at least this `match.score`, as in search."
}
}
}
]
},
"example": {
"semantic_query": "practice management software for independent dental practices",
"countries": [
"US"
],
"min_score": 0.6,
"group_by": [
"employees"
]
}
}
}
},
"responses": {
"200": {
"description": "Counts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountResponse"
},
"example": {
"total": 84,
"total_capped": false,
"would_charge": 81,
"groups": {
"employees": {
"1-10": 21,
"11-50": 38,
"51-200": 19,
"201-500": 5,
"501-1K": 1
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/search": {
"post": {
"operationId": "searchCompanies",
"tags": [
"Discovery"
],
"summary": "Search companies",
"description": "Find companies with filters, a plain-language `semantic_query`, or both.\n\n**Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and\nweb traffic by `semantic_weight`). Without it, larger companies with more web traffic come first.\n`query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks.\n\n**Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later\npages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"example": {
"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
}
}
}
},
"responses": {
"200": {
"description": "Matching companies.",
"headers": {
"X-Lookups-Remaining": {
"$ref": "#/components/headers/LookupsRemaining"
},
"X-Discoveries-Remaining": {
"$ref": "#/components/headers/DiscoveriesRemaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/companies/similar": {
"post": {
"operationId": "findSimilarCompanies",
"tags": [
"Discovery"
],
"summary": "Find similar companies",
"description": "Companies similar to 1–10 seed companies you pass in `companies`, based on what they do and who they sell to.\nAll search filters work on top. Results are sorted by `match.score` (similarity to the seeds).\n\nThe seeds are the examples you give us. They are never returned in the results and aren't charged.\nSeeds we can't find are ignored; if none are found you get a 404.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n\n`query` and `semantic_query` aren't accepted here: the seeds describe what you're looking for.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimilarRequest"
},
"example": {
"companies": [
"acmedental.io"
],
"countries": [
"US",
"CA"
],
"min_score": 0.6,
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Similar companies.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
},
"example": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/pages/search": {
"post": {
"operationId": "searchPages",
"tags": [
"Discovery"
],
"summary": "Search page summaries",
"description": "Search inside the summaries of company web pages, optionally limited to some page types and to companies\nthat match filters. Returns one result per company: its best-matching page. Sorted by `match.score`.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PageSearchRequest"
},
"example": {
"query": "14-day free trial, no credit card required",
"page_types": [
"pricing"
],
"company": {
"countries": [
"GB"
]
},
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Matching pages.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"page",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"page": {
"$ref": "#/components/schemas/PageSummary"
},
"match": {
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"type": "number",
"description": "How well the page matches `query` (0–1)."
}
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"page": {
"page_type": "pricing",
"url": "https://ledgerly.co.uk/pricing",
"summary": "Three plans from £12 to £49 per month. All plans start with a 14-day free trial; no card required."
},
"match": {
"score": 0.91
}
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
},
"/vendors/{vendor}/customers": {
"post": {
"operationId": "listVendorCustomers",
"tags": [
"Discovery"
],
"summary": "List a vendor's customers",
"description": "Companies that use a technology or service provider: named in their subprocessor list, detected on their\nwebsite, or mentioned in their job postings. Narrow the list with the same company filters as search.\nLarger companies come first.\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. To check how many you'd get\nfirst, use the free `/companies/count` with `vendors` (subprocessor lists) or `technologies` (website and job postings).\n",
"parameters": [
{
"name": "vendor",
"in": "path",
"required": true,
"description": "Slug of a technology or service provider, from `/technologies` (for example `openai`, `aws`, `stripe`).",
"schema": {
"type": "string"
},
"example": "openai"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where it must have been found: `subprocessor` list, `website`, `jobs`, or `any`."
},
"company": {
"$ref": "#/components/schemas/CompanyAttributeFilters",
"description": "Only return companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page. Valid for 24 hours."
}
}
},
"example": {
"source": "subprocessor",
"company": {
"countries": [
"GB"
],
"employees": [
"11-50",
"51-200"
]
},
"limit": 25
}
}
}
},
"responses": {
"200": {
"description": "Companies using the vendor.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"sources"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"subprocessor",
"website",
"jobs"
]
}
},
"evidence_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Page where the vendor is disclosed, when the source is a subprocessor list."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"sources": [
"subprocessor"
],
"evidence_url": "https://ledgerly.co.uk/legal/subprocessors"
}
],
"next_cursor": "c_2",
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/companies/{company}/job-postings": {
"get": {
"operationId": "listCompanyJobPostings",
"tags": [
"Job postings"
],
"summary": "List a company's job postings",
"description": "Job postings of one company, newest first. Open postings by default; pass `status=closed` or `status=all`\nto include postings that have closed.\nCosts 1 lookup unless the company is already paid for this billing month; all of its postings are then free.\n",
"parameters": [
{
"$ref": "#/components/parameters/CompanyKey"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open"
},
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
{
"name": "job_function",
"in": "query",
"description": "A value from `/values/job_functions`.",
"schema": {
"type": "string"
}
},
{
"name": "seniority",
"in": "query",
"description": "A value from `/values/job_seniorities`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Job postings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_postings",
"next_cursor",
"usage"
],
"properties": {
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_postings": [
{
"id": "job_77x2a",
"title": "Senior Backend Engineer",
"job_function": "engineering",
"seniority": "senior",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"posted_on": "2026-10-20",
"status": "open"
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 1,
"discoveries": 0
},
"already_paid": 0,
"remaining": {
"lookups": 9749,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/{id}": {
"get": {
"operationId": "getJobPosting",
"tags": [
"Job postings"
],
"summary": "Get a job posting",
"description": "The full job posting, open or closed (`status` and `closed_on` show which).\nCosts 1 lookup for its company unless already paid for this billing month.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "job_77x2a",
"description": "A job posting id from the job posting list or search endpoints."
}
],
"responses": {
"200": {
"description": "Job posting.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_posting",
"usage"
],
"properties": {
"job_posting": {
"$ref": "#/components/schemas/JobPosting"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"job_posting": {
"id": "job_77x2a",
"company": {
"id": "cmp_19ad3",
"domain": "acmedental.io",
"name": "AcmeDental",
"logo_url": null
},
"title": "Senior Backend Engineer",
"normalized_title": "backend engineer",
"job_function": "engineering",
"seniority": "senior",
"employment_type": "full_time",
"workplace_type": "remote",
"locations": [
"Austin, TX, United States"
],
"salary": {
"min": 150000,
"max": 180000,
"currency": "USD",
"period": "year"
},
"technologies": [
"python",
"postgresql",
"aws"
],
"experience_years": 5,
"education": null,
"benefits": [
"health insurance",
"401k"
],
"visa_sponsorship": false,
"summary": "Build the scheduling and billing services behind AcmeDental's practice management platform.",
"url": "https://jobs.example.com/acmedental/77x2a",
"posted_on": "2026-10-20",
"closed_on": null,
"status": "open"
},
"usage": {
"charged": {
"lookups": 0,
"discoveries": 0
},
"already_paid": 1,
"remaining": {
"lookups": 9750,
"discoveries": 1977
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/job-postings/search": {
"post": {
"operationId": "searchJobPostings",
"tags": [
"Job postings"
],
"summary": "Search job postings",
"description": "Search job postings across companies. Results are grouped by company, newest postings first, and include\nonly the postings that match (up to 10 per company).\n\nCosts 1 discovery per company returned that isn't already paid for this billing month. That covers all of that\ncompany's postings: listing them with `GET /companies/{company}/job-postings` is then free.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobSearchRequest"
},
"example": {
"title": "data engineer",
"technologies": [
"snowflake"
],
"posted_within_days": 30,
"job_countries": [
"GB"
],
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "Job postings grouped by company.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"company",
"job_postings"
],
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"job_postings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobPostingSummary"
}
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"results": [
{
"company": {
"id": "cmp_7tw3e",
"domain": "ledgerly.co.uk",
"name": "Ledgerly",
"logo_url": null
},
"job_postings": [
{
"id": "job_k21m9",
"title": "Data Engineer",
"job_function": "engineering",
"seniority": "mid",
"workplace_type": "hybrid",
"locations": [
"London, United Kingdom"
],
"posted_on": "2026-10-28",
"status": "open"
}
]
}
],
"next_cursor": null,
"usage": {
"charged": {
"lookups": 0,
"discoveries": 1
},
"already_paid": 0,
"remaining": {
"lookups": 9750,
"discoveries": 1976
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/AllowanceExhausted"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Your API key, sent as `Authorization: Bearer `. Create keys in the dashboard."
}
},
"headers": {
"LookupsRemaining": {
"description": "Lookups left in this billing period.",
"schema": {
"type": "integer"
}
},
"DiscoveriesRemaining": {
"description": "Discoveries left in this billing period.",
"schema": {
"type": "integer"
}
}
},
"parameters": {
"CompanyKey": {
"name": "company",
"in": "path",
"required": true,
"description": "The company's domain (for example `stripe.com`) or its CompanySpec id (for example `cmp_8f2k1`).",
"schema": {
"type": "string"
},
"example": "acmedental.io"
},
"ShowIcp": {
"name": "show_icp",
"in": "query",
"description": "Include `icp`: what they do, the problem they solve and who they sell to.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPricing": {
"name": "show_pricing",
"in": "query",
"description": "Include `pricing`: a summary of their pricing page (plans, prices, free trial).",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowDescription": {
"name": "show_description",
"in": "query",
"description": "Include `long_description`.",
"schema": {
"type": "boolean",
"default": false
}
},
"ShowPages": {
"name": "show_pages",
"in": "query",
"description": "Include `pages`: the most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"schema": {
"type": "boolean",
"default": false
}
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"description": "The `next_cursor` from the previous page. Valid for 24 hours. Fetching later pages charges for new companies on them.",
"schema": {
"type": "string"
}
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing or invalid API key.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"AllowanceExhausted": {
"description": "Your monthly allowance for this kind of request is used up. Requests resume next period or after an upgrade. You are never billed overage.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/allowance-exhausted",
"title": "Allowance exhausted",
"status": 402,
"detail": "You have used all 2,000 discoveries for the billing month ending 2026-12-02.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"NotFound": {
"description": "Not found.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/not-found",
"title": "Not found",
"status": 404,
"detail": "No company found for not-a-real-company.example.",
"request_id": "req_01JC8X4T2M"
}
}
}
},
"ValidationError": {
"description": "The request is invalid.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/validation-error",
"title": "Validation error",
"status": 422,
"detail": "employees[0] must be one of: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.",
"errors": [
{
"field": "employees[0]",
"message": "Unknown value '10-50'"
}
],
"request_id": "req_01JC8X4T2M"
}
}
}
},
"RateLimited": {
"description": "Too many requests. Retry after the number of seconds in `Retry-After`.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
},
"example": {
"type": "https://companyspec.com/docs/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 2 seconds.",
"request_id": "req_01JC8X4T2M"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An error, following RFC 9457 (problem details).",
"required": [
"type",
"title",
"status"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URL identifying the error type. See Errors."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"available_page_types": {
"type": "array",
"description": "Only on `page-not-available` errors.",
"items": {
"$ref": "#/components/schemas/PageType"
}
},
"errors": {
"type": "array",
"description": "Only on validation errors: one entry per invalid field.",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "For example `employees[0]`."
},
"message": {
"type": "string"
}
}
}
},
"request_id": {
"type": "string",
"description": "Include this when you contact support."
}
}
},
"NextCursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to get the next page. `null` when there are no more results."
},
"Allowance": {
"type": "object",
"required": [
"used",
"limit"
],
"properties": {
"used": {
"type": "integer",
"description": "Companies charged so far this billing month."
},
"limit": {
"type": "integer",
"description": "Companies included in your plan each billing month."
}
}
},
"Account": {
"type": "object",
"required": [
"plan",
"period",
"lookups",
"discoveries"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"starter",
"growth",
"pro",
"scale"
],
"description": "Your plan. See Billing & usage for what each plan includes."
},
"period": {
"type": "object",
"required": [
"start",
"end"
],
"description": "Your current billing month. Allowances and \"already paid\" companies reset when it ends.",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
},
"lookups": {
"$ref": "#/components/schemas/Allowance"
},
"discoveries": {
"$ref": "#/components/schemas/Allowance"
}
}
},
"Usage": {
"type": "object",
"description": "What this request cost and what is left this billing month.",
"required": [
"charged",
"already_paid",
"remaining"
],
"properties": {
"charged": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer",
"description": "Companies newly charged as lookups by this request."
},
"discoveries": {
"type": "integer",
"description": "Companies newly charged as discoveries by this request."
}
}
},
"already_paid": {
"type": "integer",
"description": "Companies in this response that were already paid for this billing month, so they were not charged again."
},
"remaining": {
"type": "object",
"required": [
"lookups",
"discoveries"
],
"properties": {
"lookups": {
"type": "integer"
},
"discoveries": {
"type": "integer"
}
}
},
"allowance_reached": {
"type": "boolean",
"description": "`true` when results were cut short because your allowance ran out during this request. You received as many companies as your remaining allowance covered."
}
}
},
"ValueField": {
"type": "string",
"enum": [
"industries",
"naics_codes",
"sic_codes",
"countries",
"states",
"cities",
"regions",
"type",
"employees",
"revenue",
"customer_types",
"customer_segments",
"compliance",
"page_types",
"require",
"hire_departments",
"hire_seniorities",
"workforce_departments",
"job_functions",
"job_seniorities",
"workplace_types",
"employment_types",
"funding_rounds",
"news_categories",
"technology_categories"
],
"description": "A filter name."
},
"ValuesResponse": {
"type": "object",
"required": [
"field",
"values",
"next_cursor"
],
"properties": {
"field": {
"$ref": "#/components/schemas/ValueField"
},
"values": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string",
"description": "Use this in filters."
},
"label": {
"type": "string"
},
"companies": {
"type": "integer",
"description": "Number of companies with this value."
}
}
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
}
}
},
"PageType": {
"type": "string",
"description": "A type of page on a company's website.",
"enum": [
"home",
"pricing",
"about",
"careers",
"blog",
"legal",
"integrations",
"case_studies",
"login",
"status",
"engineering",
"support",
"cart",
"compliance"
]
},
"PageSummary": {
"type": "object",
"required": [
"page_type",
"url",
"summary"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
},
"summary": {
"type": "string",
"description": "A paragraph summarising the page."
}
}
},
"PageLink": {
"type": "object",
"required": [
"page_type",
"url"
],
"properties": {
"page_type": {
"$ref": "#/components/schemas/PageType"
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"EmployeeRange": {
"type": "string",
"enum": [
"1-10",
"11-50",
"51-200",
"201-500",
"501-1K",
"1K-5K",
"5K-10K",
"over-10K"
]
},
"RevenueRange": {
"type": "string",
"enum": [
"under-1m",
"1m-10m",
"10m-50m",
"50m-100m",
"100m-200m",
"200m-1b",
"over-1b"
]
},
"CompanyType": {
"type": "string",
"enum": [
"private",
"public",
"self-employed",
"self-owned",
"partnership",
"nonprofit",
"educational",
"government"
]
},
"FundingRoundType": {
"type": "string",
"enum": [
"seed",
"angel",
"venture",
"series_a",
"series_b",
"series_c",
"series_d",
"series_e",
"series_f",
"series_g",
"series_h",
"debt_financing",
"other"
]
},
"Location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2."
},
"country": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
}
}
},
"CompanyRef": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"Company": {
"type": "object",
"required": [
"id",
"domain",
"name"
],
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"website": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": {
"type": [
"string",
"null"
],
"description": "One-line description."
},
"logo_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyType"
},
{
"type": "null"
}
],
"description": "Ownership type: `private`, `public`, `nonprofit`, `government`, `educational`, `partnership`, `self-employed` or `self-owned`."
},
"founded_year": {
"type": [
"integer",
"null"
]
},
"ipo_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"industry": {
"type": [
"string",
"null"
]
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"description": "Who they sell to: `B2B`, `B2C`, `B2G`.",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"description": "Kinds of customers they sell to, for example `enterprise`, `smb`, `government`.",
"items": {
"type": "string"
}
},
"compliance": {
"type": "array",
"description": "Certifications and standards they claim on their website, for example `SOC 2`, `HIPAA`, `ISO 27001`.",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"description": "Technologies they use, detected on their website or in their job postings (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"description": "Service providers named in their subprocessor list, for example `aws` or `stripe` (slugs from `/technologies`).",
"items": {
"type": "string"
}
},
"employees": {
"oneOf": [
{
"$ref": "#/components/schemas/EmployeeRange"
},
{
"type": "null"
}
],
"description": "Employee range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"employee_count": {
"type": [
"integer",
"null"
]
},
"revenue": {
"oneOf": [
{
"$ref": "#/components/schemas/RevenueRange"
},
{
"type": "null"
}
],
"description": "Annual revenue range in USD: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"location": {
"$ref": "#/components/schemas/Location"
},
"office_locations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Location"
},
{
"type": "object",
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
}
}
}
]
}
},
"parent": {
"oneOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "null"
}
]
},
"subsidiaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyRef"
}
},
"socials": {
"type": "object",
"properties": {
"linkedin_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"twitter_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"facebook_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"youtube_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"github_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"open_jobs": {
"type": "integer",
"description": "Number of open job postings."
},
"web": {
"type": "object",
"properties": {
"traffic_rank": {
"type": [
"integer",
"null"
],
"description": "Global rank of their website by traffic. Lower means more traffic."
}
}
},
"icp": {
"type": [
"string",
"null"
],
"description": "Only with `show_icp=true`. An AI-written paragraph from their website: what they provide, the problem they solve and who their customers likely are."
},
"pricing": {
"type": [
"string",
"null"
],
"description": "Only with `show_pricing=true`. An AI-written summary of their pricing page: plans, prices, free trial."
},
"long_description": {
"type": [
"string",
"null"
],
"description": "Only with `show_description=true`. The long company description."
},
"pages": {
"type": "array",
"description": "Only with `show_pages=true`. The most useful pages on their website, with URLs. Get the summary of any of them with `GET /companies/{company}/pages/{page_type}`.",
"items": {
"$ref": "#/components/schemas/PageLink"
}
}
}
},
"EnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Domains or CompanySpec ids.",
"items": {
"type": "string"
}
},
"show_icp": {
"type": "boolean",
"default": false
},
"show_pricing": {
"type": "boolean",
"default": false
},
"show_description": {
"type": "boolean",
"default": false
},
"show_pages": {
"type": "boolean",
"default": false
}
}
},
"ResolveCandidate": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyRef"
},
{
"type": "object",
"required": [
"confidence"
],
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
]
},
"ResolveResponse": {
"type": "object",
"required": [
"match",
"alternatives"
],
"properties": {
"match": {
"oneOf": [
{
"$ref": "#/components/schemas/ResolveCandidate"
},
{
"type": "null"
}
]
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolveCandidate"
}
}
}
},
"TechnologySummary": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"companies": {
"type": "integer",
"description": "Companies currently using it."
}
}
},
"TechnologyProfile": {
"allOf": [
{
"$ref": "#/components/schemas/TechnologySummary"
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing_models": {
"type": "array",
"items": {
"type": "string"
}
},
"license_types": {
"type": "array",
"items": {
"type": "string"
}
},
"github_repo": {
"type": [
"string",
"null"
]
},
"integrates_with": {
"type": "array",
"description": "Slugs of technologies it integrates with.",
"items": {
"type": "string"
}
},
"made_by": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
},
"description": "The company that makes this technology."
}
}
}
]
},
"CompanyTechnology": {
"type": "object",
"required": [
"slug",
"name",
"sources"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"description": "Where it was detected.",
"items": {
"type": "string",
"enum": [
"website",
"jobs"
]
}
},
"first_seen": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When we first detected it."
},
"removed_on": {
"type": [
"string",
"null"
],
"format": "date",
"description": "When it was no longer detected, if removed."
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Why we think the company uses it."
}
}
},
"Headcount": {
"type": "object",
"required": [
"departments",
"history"
],
"properties": {
"employee_count": {
"type": [
"integer",
"null"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"employee_count"
],
"properties": {
"department": {
"type": "string",
"description": "A value from `/values/workforce_departments`."
},
"employee_count": {
"type": "integer"
}
}
}
},
"history": {
"type": "array",
"items": {
"type": "object",
"required": [
"month",
"employee_count"
],
"properties": {
"month": {
"type": "string",
"description": "YYYY-MM"
},
"employee_count": {
"type": "integer"
}
}
},
"description": "Total headcount per month for the last 12 months."
}
}
},
"HiresResponse": {
"type": "object",
"required": [
"within_days",
"total",
"by_department",
"by_seniority",
"items"
],
"properties": {
"within_days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"by_department": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_seniority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"department",
"seniority",
"start_date"
],
"properties": {
"department": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"start_date": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"Investor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
},
"Funding": {
"type": "object",
"required": [
"rounds",
"investors",
"acquisitions"
],
"properties": {
"total_funding_usd": {
"type": [
"integer",
"null"
]
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"oneOf": [
{
"$ref": "#/components/schemas/FundingRoundType"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"announced_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"amount_usd": {
"type": [
"integer",
"null"
]
},
"pre_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"post_money_valuation_usd": {
"type": [
"integer",
"null"
]
},
"lead_investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
}
}
}
},
"investors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Investor"
}
},
"acquisitions": {
"type": "array",
"description": "Companies this company acquired.",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"NewsEvent": {
"type": "object",
"required": [
"id",
"category",
"date"
],
"properties": {
"id": {
"type": "string"
},
"category": {
"type": "string",
"description": "A value from `/values/news_categories`."
},
"category_group": {
"type": [
"string",
"null"
],
"description": "The broader group the category belongs to (listed with each category in `/values/news_categories`)."
},
"date": {
"type": "string",
"format": "date"
},
"summary": {
"type": [
"string",
"null"
],
"description": "One-sentence summary of the event."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "For financing events."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The article or announcement the event comes from."
}
}
},
"JobPostingSummary": {
"type": "object",
"required": [
"id",
"title",
"status"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"seniority": {
"type": [
"string",
"null"
]
},
"workplace_type": {
"type": [
"string",
"null"
],
"enum": [
"onsite",
"hybrid",
"remote",
null
]
},
"locations": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"open",
"closed"
]
}
}
},
"JobPosting": {
"allOf": [
{
"$ref": "#/components/schemas/JobPostingSummary"
},
{
"type": "object",
"properties": {
"company": {
"$ref": "#/components/schemas/CompanyRef"
},
"normalized_title": {
"type": [
"string",
"null"
],
"description": "The job title in standard form, without levels or extras (for example `backend engineer`). Filter on it with `normalized_titles`."
},
"employment_type": {
"type": [
"string",
"null"
]
},
"salary": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"period": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
"month",
"year",
null
]
}
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"experience_years": {
"type": [
"integer",
"null"
]
},
"education": {
"type": [
"string",
"null"
]
},
"benefits": {
"type": "array",
"items": {
"type": "string"
}
},
"visa_sponsorship": {
"type": [
"boolean",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"closed_on": {
"type": [
"string",
"null"
],
"format": "date"
}
}
}
]
},
"Range": {
"type": "object",
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
}
}
},
"Operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"description": "How the values in the list combine. `and` (default): the company must have all of them. `or`: it must have at least one."
},
"CompanyFilters": {
"description": "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).",
"allOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "Match against company name and domain (contains)."
},
"semantic_query": {
"type": "string",
"maxLength": 500,
"description": "Describe the companies you want in plain language, including who they sell to.",
"examples": [
"practice management software for independent dental practices"
]
},
"semantic_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "How much to favour relevance to `semantic_query` (1) over company size and web traffic (0)."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
}
]
},
"ResultControls": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Results per page (1–100). A search returns at most 1,000 results in total."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (0–1). For `semantic_query` it is relevance; for `/companies/similar` it is similarity to the seeds."
},
"show_icp": {
"type": "boolean",
"default": false,
"description": "Include the ICP paragraph (what they do and who they sell to) in each result. No extra cost."
},
"show_pricing": {
"type": "boolean",
"default": false,
"description": "Include the pricing summary in each result. No extra cost."
},
"show_description": {
"type": "boolean",
"default": false,
"description": "Include the long description in each result. No extra cost."
},
"show_pages": {
"type": "boolean",
"default": false,
"description": "Include the list of most useful pages on their website in each result. No extra cost."
}
}
},
"SearchRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CompanyFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"SimilarRequest": {
"allOf": [
{
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Seed companies, by domain or CompanySpec id.",
"items": {
"type": "string"
}
},
"similarity_weight": {
"type": "number",
"minimum": -1,
"maximum": 1,
"default": 0,
"description": "Higher favours closer matches; lower favours larger, more established companies."
}
}
},
{
"$ref": "#/components/schemas/CompanyAttributeFilters"
},
{
"$ref": "#/components/schemas/ResultControls"
}
]
},
"PageSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 500,
"description": "What to look for in page summaries, in plain language. For example `14-day free trial, no credit card required`."
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "Only search these page types. Default: all."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters",
"description": "Only search pages of companies that match these filters."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"min_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum `match.score` (how well the page matches `query`)."
}
}
},
"JobSearchRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"description": "Text to match in job titles."
},
"normalized_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_functions`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/job_seniorities`."
},
"workplace_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"onsite",
"hybrid",
"remote"
]
}
},
"employment_types": {
"type": "array",
"items": {
"type": "string"
}
},
"job_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries where the job is located (ISO alpha-2)."
},
"job_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Job locations from `/values/cities`."
},
"salary": {
"$ref": "#/components/schemas/Range",
"description": "Salary range, in `salary_currency`."
},
"salary_currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "ISO currency code for `salary`, for example `USD`. Only postings with a salary in this currency match; amounts are not converted."
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technologies mentioned in the posting."
},
"visa_sponsorship": {
"type": "boolean"
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
},
"status": {
"type": "string",
"enum": [
"open",
"closed",
"all"
],
"default": "open",
"description": "`open` (default), `closed` or `all`. Closed postings stay available, with `closed_on` set."
},
"company": {
"$ref": "#/components/schemas/CompanyFilters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Companies per page."
},
"cursor": {
"type": "string"
}
}
},
"SearchResult": {
"type": "object",
"required": [
"company",
"match"
],
"properties": {
"company": {
"$ref": "#/components/schemas/Company"
},
"match": {
"type": [
"object",
"null"
],
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"reason": {
"type": [
"string",
"null"
],
"description": "Short explanation of why it matched."
}
}
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"results",
"next_cursor",
"usage"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResult"
}
},
"next_cursor": {
"$ref": "#/components/schemas/NextCursor"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"CountResponse": {
"type": "object",
"required": [
"total",
"total_capped",
"would_charge"
],
"properties": {
"total": {
"type": "integer",
"description": "Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with `semantic_query`."
},
"total_capped": {
"type": "boolean",
"description": "`true` when there are more matches than `total` shows. Add filters to narrow it down."
},
"would_charge": {
"type": "integer",
"description": "How many of the counted companies are not yet paid for this billing month."
},
"groups": {
"type": "object",
"description": "Present when `group_by` is set. With `semantic_query`, groups cover the counted (top 1,000) matches.",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}
},
"CompanyAttributeFilters": {
"type": "object",
"description": "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).",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "HQ countries (ISO 3166-1 alpha-2). Matches any."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/states`. Matches any."
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/cities`. Matches any."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/regions`. Matches any."
},
"office_locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any office, not just HQ. Values from `/values/cities` or country codes. Matches any."
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
},
"description": "Ownership type. Matches any. Values from `/values/type`."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
},
"description": "Employee ranges. Matches any. Values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`, `5K-10K`, `over-10K`."
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
},
"description": "Annual revenue ranges (USD). Matches any. Values: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`, `200m-1b`, `over-1b`."
},
"founded_year": {
"$ref": "#/components/schemas/Range",
"description": "Year range, for example `{\"min\": 2015, \"max\": 2022}`."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/industries`. Matches any."
},
"naics_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,6}$"
},
"description": "2–6 digits. Shorter codes include all codes beneath them. Matches any."
},
"sic_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]{2,4}$"
},
"description": "Values from `/values/sic_codes`. Matches any."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords from the company profile. Combined with `keywords_operator`."
},
"keywords_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Who they sell to: `B2B`, `B2C`, `B2G`. Combined with `customer_types_operator`."
},
"customer_types_operator": {
"$ref": "#/components/schemas/Operator"
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Kinds of customers, for example `enterprise`, `smb`, `government`. Values from `/values/customer_segments`. Combined with `customer_segments_operator`."
},
"customer_segments_operator": {
"$ref": "#/components/schemas/Operator"
},
"compliance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Claimed certifications, for example `SOC 2`, `HIPAA`. Values from `/values/compliance`. Combined with `compliance_operator`."
},
"compliance_operator": {
"$ref": "#/components/schemas/Operator"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Technology slugs from `/technologies`. Combined with `technologies_operator`."
},
"technologies_operator": {
"$ref": "#/components/schemas/Operator"
},
"technology_source": {
"type": "string",
"enum": [
"website",
"jobs",
"any"
],
"default": "any",
"description": "Where a technology must have been found: `website`, `jobs` or `any` (default)."
},
"vendors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Service providers named in the subprocessor list (slugs from `/technologies`). Combined with `vendors_operator`."
},
"vendors_operator": {
"$ref": "#/components/schemas/Operator"
},
"page_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PageType"
},
"description": "The company must have all of these page types."
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
},
"description": "Has raised any of these round types. Values from `/values/funding_rounds`."
},
"funding_amount": {
"$ref": "#/components/schemas/Range",
"description": "Total funding range in USD."
},
"funding_year": {
"$ref": "#/components/schemas/Range",
"description": "Year of the most recent round."
},
"investors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Backed by any of these investors (names or domains)."
},
"workforce_size": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department": {
"type": "string",
"default": "overall",
"description": "A value from `/values/workforce_departments`, or `overall`."
},
"min": {
"type": [
"integer",
"null"
]
},
"max": {
"type": [
"integer",
"null"
]
}
}
},
"description": "Headcount ranges per department, for example `[{\"department\": \"engineering\", \"min\": 20}]`. Departments from `/values/workforce_departments`, or `overall`. All conditions must match."
},
"workforce_growth": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"m6",
"y1",
"y2"
]
},
"department": {
"type": "string",
"default": "overall"
},
"min_percent": {
"type": [
"number",
"null"
],
"description": "15 means 15% growth; -10 means a 10% decline."
},
"max_percent": {
"type": [
"number",
"null"
]
}
},
"description": "Headcount growth over a period (`m6` = 6 months, `y1` = 1 year, `y2` = 2 years), optionally for one department, as a percentage range."
},
"recent_hires": {
"type": "object",
"description": "Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.",
"properties": {
"departments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_departments`."
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/hire_seniorities`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 90
},
"min_count": {
"type": "integer",
"minimum": 1,
"default": 1
}
}
},
"hiring": {
"type": "object",
"description": "Companies with matching open job postings.",
"properties": {
"has_open_jobs": {
"type": "boolean"
},
"min_open_jobs": {
"type": "integer",
"minimum": 1
},
"job_functions": {
"type": "array",
"items": {
"type": "string"
}
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"posted_within_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
},
"news": {
"type": "object",
"description": "Companies with matching news events.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values from `/values/news_categories`."
},
"within_days": {
"type": "integer",
"minimum": 1,
"maximum": 730
}
}
},
"require": {
"type": "array",
"description": "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).",
"items": {
"type": "string",
"enum": [
"linkedin",
"twitter",
"icp",
"pricing_page",
"funding",
"revenue",
"founded_year",
"hq_city",
"open_jobs"
]
}
},
"exclude": {
"type": "object",
"description": "Remove companies that match any of these, for example `{\"domains\": [\"acme.com\"], \"employees\": [\"1-10\"]}`.",
"properties": {
"domains": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
}
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyType"
}
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployeeRange"
}
},
"revenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RevenueRange"
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"naics_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_types": {
"type": "array",
"items": {
"type": "string"
}
},
"customer_segments": {
"type": "array",
"items": {
"type": "string"
}
},
"technologies": {
"type": "array",
"items": {
"type": "string"
}
},
"vendors": {
"type": "array",
"items": {
"type": "string"
}
},
"funding_rounds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FundingRoundType"
}
}
}
}
}
}
}
}
}
```