Company Search API

Cleanlist's Company Search API finds B2B accounts by industry, headcount and location, and charges 0 credits to run. POST /api/v2/search/companies returns matched companies with domain, industry and employee count, plus a task_id for enrichment. A companion endpoint, POST /search/companies/similar, returns lookalikes for a seed company. Search is free; you spend 1 credit per company only when you enrich one. This page also documents which filter keys are accepted but empty, verified against the live API on 2026-08-18.

How do I call the Cleanlist Company Search API?

POST https://api.cleanlist.ai/api/v2/search/companies with a clapi_ Bearer token and the companies:read scope.

curl -X POST https://api.cleanlist.ai/api/v2/search/companies \
  -H "Authorization: Bearer clapi_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "industries": ["Software Development"],
      "employee_count_ranges": ["51-200", "201-500"],
      "locations": ["San Francisco"]
    },
    "limit": 25
  }'

Which company filters actually work?

This is the most important table on the page, because several keys are accepted by the request validator and then match nothing. Verified against the live API on 2026-08-18.

Why does funding_stages return zero results?

Because the request validator accepts the key but the underlying column is not populated. A live call on 2026-08-18 with {"industries": ["Software Development"], "employee_count_ranges": ["51-200"], "funding_stages": ["Series B"]} returned total: 0, while the same filters without funding_stages return thousands.

This is a data-availability limit, not a rejection. Cleanlist does not carry funding-stage, revenue-band or technographic data, and does not sell intent data. Anyone evaluating Cleanlist against a vendor that does should weigh that directly rather than discover it in a zero-result response.

How do I approximate "funded and growing" without a funding filter?

Use headcount as the proxy. The 51-200 and 201-500 bands are reliably post-Series-A and pre-enterprise, which is the segment most people mean when they ask for "recently funded".

{
  "filters": {
    "industries": ["Software Development", "Financial Services"],
    "employee_count_ranges": ["51-200", "201-500"],
    "locations": ["San Francisco", "New York", "Toronto"]
  },
  "limit": 200
}

Because Cleanlist charges 0 credits for search, you can run several variations of this and compare total counts before committing to one. Sizing costs nothing.

Why is industries: ["Finance"] returning nothing useful?

Industries use the LinkedIn industry taxonomy, which uses specific labels. "Finance" is not a taxonomy value; "Financial Services" is. Likewise "Software" is not a value and "Software Development" is.

The same applies to locations: send a bare city name like ["San Francisco"], not the full "San Francisco, California, United States" literal. The literal form is exact-string matched and silently drops roughly half of real matches, because records are stored variously as "Toronto, ON", "North York" and similar.

How do I find companies similar to my best customers?

POST /api/v2/search/companies/similar with a seed company. It returns companies with comparable firmographics.

curl -X POST https://api.cleanlist.ai/api/v2/search/companies/similar \
  -H "Authorization: Bearer clapi_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "shopify.com", "limit": 25}'

Be clear about what this is. Cleanlist synthesizes lookalikes from firmographic similarity rather than running a trained lookalike model over an owned graph. It is a strong way to widen a segment from an account you already know converts. It is not a scored propensity model, and Cleanlist does not present it as one.

What does a Company Search response look like?

{
  "task_id": "cl-task_...",
  "entity_kind": "company",
  "results": [
    {
      "company_id": "...",
      "name": "Example Corp",
      "domain": "example.com",
      "industry": "Software Development",
      "employee_count": 180
    }
  ],
  "total": 1432,
  "cursor": "H4sIA...",
  "credits_charged": 0,
  "truncation_warning": null
}

total is the full match count regardless of limit, so one free call tells you how big a market is.

How do I get the people at those companies?

Company search returns accounts. To get contacts, take the domains and feed them into People Search:

{
  "filters": {
    "company_domains": ["example.com", "acme.com"],
    "management_levels": ["VP", "Director"],
    "departments": ["Sales", "Marketing"]
  },
  "limit": 100
}

Both calls are free. The account-based prospecting loop in Cleanlist costs nothing until the moment you enrich a person for an email or a phone number, at 1 and 10 credits respectively.

What does company enrichment cost?

Company enrichment is synchronous. Person enrichment is asynchronous and returns a workflow_id you poll. See Polling & Async.

How do I paginate through company results?

Pass the cursor from the previous response back on the next request. Cursors are opaque; do not construct them. cursor: null means you have reached the end. There is no offset or page-number pagination.

What are the rate limits on company search?

60 requests per minute per organization and 30 per minute per API key.

Unlike People Search, company search is not subject to the 60-per-UTC-day cap. That cap applies to People Search only. If you are building an account-based workflow, front-load the company work and pull people in fewer, larger People Search calls.

Can an AI agent call the Company Search API?

Yes, and it is the intended pattern. Because search costs nothing and every paid operation is gated behind a signed quote from POST /credits/estimate, an agent can explore the account universe freely and still cannot spend credits without pricing the job first. The quote is HMAC-signed with a 5-minute TTL and validated server-side against the actual cohort.

The Cleanlist MCP server exposes the same search_companies and find_similar_companies tools to Claude directly, so an agent connects over OAuth with no API key to paste.

What error does a bad company search return?

The single v2 error envelope applies:

{
  "code": "insufficient_scope",
  "problem": "The credential does not carry companies:read.",
  "fix": "Grant companies:read to this API key in Settings > API Keys.",
  "retryable": false,
  "docs_url": "https://docs.cleanlist.ai/mcp-api/errors",
  "request_id": "req_01J..."
}

Note that an empty result set is not an error. A search with funding_stages returns HTTP 200 with total: 0. Check total rather than relying on a status code.

FAQ

Is the Cleanlist Company Search API free?

The search call is free and returns credits_charged: 0. API access requires a Pro plan ($229/mo) or above, or AppSumo Tier 5+. Company enrichment costs 1 credit per company and is billed only when data is returned.

Does Cleanlist have technographic or intent data?

No. There is no technographic filtering and no intent data. The technologies filter key is accepted by the validator but returns no matches.

How large can a company search be?

limit accepts 1 to 500 and defaults to 25. Use cursor pagination for larger cohorts. total reports the full match count either way.

What is the difference between names and domains?

names matches the company's display name and is ambiguous across companies that share one. domains matches the company's web domain and is the reliable identifier. Prefer domains whenever you have them.

Where does company data come from?

Cleanlist is an orchestration layer over external providers rather than a data vendor with an owned database. Company search and company enrichment are served by a search provider; contact enrichment runs a multi-provider waterfall with verification before results are returned.

Last updated: August 18, 2026. Filter behaviour, including the empty funding_stages, revenue_ranges and technologies columns, was verified against the live API on that date.