Recipes

Filter companies

Most of the work in any /companies flow is figuring out which companies you actually want. The filter surface is wide — over twenty parameters spanning firmographics, behaviour, geography, industry, tags, and more. The simple cases (filter by domain, by country, by tag) are trivial. The interesting questions show up once you start combining ranges, lists, and exclusions. Here's how we navigate it.

Each filter narrows the set. Most of the work in any /companies query is picking the right combination.

Endpoint

GET /v1.3/companies

Auth: account-scoped API key, or bearer token with account_id. The rest of this recipe walks the filter surface — what each dimension covers, the patterns we use most, and how filters compose.

Filter dimensions

Eight dimensions cover the surface. Most filters slot into one of them.

Dimension	Params	What it covers
Identity	`id, domain`	Pinpoint a single company.
Status & tags	`label, tags, NOT_tags, search`	Target-audience flag, lifecycle tags, free-text search.
Behavioural	`total_visits, pageviews, pagesearch, NOT_pagesearch, time, last_visit`	Website activity — counts, specific pages, recency.
Time-based	`inserted_date, changed_date, from_changed_time`	When the record was added or last changed in your account.
Firmographic	`employees, revenue, founded, rating`	Company traits — size, age, customer rating.
Geographic	`country_code, city`	Where the company is registered.
Industry	`nace, naics`	Industry codes (numerical, comma-separated for multiples).
Technographic	`apps`	Apps and technologies the company is known to use.

Common patterns

The combinations we reach for most often.

Pattern	Filters	Why
Target-audience companies with high engagement	`label=1 + total_visits=5: + pageviews=10:`	In-target accounts that show real interest.
Exclude already-synced records	`NOT_tags=synced`	Skip records you have already processed downstream.
Companies in your country, by size	`country_code=NL + employees=50:500`	Geo + firmographic for ICP-style filtering.
Recent visitors using a specific tech stack	`apps=hubspot,salesforce + last_visit=<7-days-ago>:`	Technographic + behavioural for triggered outreach.
Disqualified leads to clean up	`label=-1 + tags=competitor`	Find records flagged as competitor for review or removal.

Combining filters

Filters compose with AND — every filter you add must match. Within a single filter, the syntax depends on the data shape: numeric ranges use a colon, multi-value lists use commas, exclusions use a NOT_ prefix.

Mechanism	Syntax	Example
Range	`min:max · :max · min:`	`total_visits=5:10`
Multi-value list	`comma-separated`	`tags=lead,customer`
Exclusion	`NOT_ prefix`	`NOT_tags=churned`
Combination	`all params AND-combined`	`country_code=NL & employees=50:`

Considerations

Point	Detail
Tags are case-sensitive	Customer ≠ customer. Pick a convention and stick with it.
URL-encode search values	Special characters in the free-text query need encoding before they hit the URL.
search ≠ structured filters	search is fuzzy free-text — good for discovery. Structured filters are exact — good for precision.
data_exists for data quality	Filter on availability — e.g. data_exists=email,phone — to skip records missing a key field.
profile to slim payloads	Limit returned fields with profile=basic_profile when you process records in bulk.

Errors & retry

Sort responses into the usual three buckets.

Bucket	Examples	What to do
Transient	`network`, `5xx`, `429`	Retry with exponential backoff (1s → 2s → 4s, capped). On `429`, respect `Retry-After` if present.
Permanent	`4xx` (other than 429)	Log and stop. Usually a config or auth issue — retrying won't help.
Success	`200`	Iterate over `companies[]`; `found` is the total before pagination.