Skip to main content
POST
Company search: exact filters, one fixed sort

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Needs at least one filter, or q, similar_to or similar_to_many (enforced in the handler — JSON Schema can't express it cleanly with optional fields). Results are one row per company record (website): two websites that share an ABN are two results.

Needs at least one filter, or q, similar_to or similar_to_many (enforced in the handler — JSON Schema can't express it cleanly with optional fields). Results are one row per company record (website): two websites that share an ABN are two results.

q
string

Free text that ORDERS the results by fit (sort: relevance): its meaning matched against each company's description, fused with a word match on names and specialties that needs EVERY word of q (small words like "the" ignored), so keep q to the few words that describe the company ("commercial cleaning", not "companies that do commercial cleaning in Sydney"). It only ranks; it never filters, and nothing is read out of it. Put places in filters.state / filters.locality, a kind of company with no industry label in filters.keywords, and use lookup_by_name for one specific company. Each of its two rankings reaches only its top 600 (about 1,200 together), so it gives the best fits first, not all of them; leave it out when the filters already say what kind of company.

Required string length: 1 - 1000
similar_to
string

Registrable domain (or FQDN) of a seed company. Its stored vector is used as the query. 404 if the seed has no embedding.

Required string length: 1 - 255
similar_to_many
string[]

Lookalikes of a list of companies: 1–10 registrable domains of seed companies (e.g. a customer list). Returns companies like the seeds as a group; the seeds themselves are never in results. A seed with no embedding is listed in the response's seeds_missing instead of failing the search — 404 only when no seed has one. Use either similar_to or similar_to_many, not both.

Required array length: 1 - 10 elements
Required string length: 1 - 255
filters
object

Exact filters: a result passes every filter set. A list-valued filter takes one value or a non-empty list (matches any); an empty list is a 400 — omit the filter instead.

sort

The order of the results, one of a fixed list. relevance: fit to q or likeness to the seed(s) — the default when q, similar_to or similar_to_many is set, and a 400 without one. best_known: the best-known companies first — the default for a filters-only search. largest: biggest LinkedIn size band first, no band last, then best known within a band. best_known and largest with q or a seed is a 400: put the kind of company into filters instead. The sort applied is echoed in interpreted.sort.

Available options:
relevance
limit
integer
default:25

Results per page, 0–100. 0 is a count-only search: no results, just total (and offset is ignored). With q, total is the whole filtered pool, so a count says little about how many fit the words.

Required range: 0 <= x <= 100
offset
integer
default:0
Required range: 0 <= x <= 10000
ids_only
boolean

true answers { ids, total, total_is_capped } instead of cards: the company ids of the same page, in the same order, with the same filters / sort / limit (0–100) / offset. Ids-only searches (like limit: 0 counts) do not use the daily allowance of free search rows.

exclude_owned
boolean

true leaves out every company you already own (have unlocked), from the results AND from total, in card, count (limit: 0) and ids-only searches. Has no effect for a token with no user.

tz
string

IANA timezone (e.g. Australia/Sydney, the default) used to render signals.news.last_published_at as a calendar day and to interpret news_published_after as local midnight. Unknown zones are rejected with 400.

Maximum string length: 64

Response

Default Response

Search results in sort order.

total
integer | null
required

total is how many companies pass every applied filter (seeds excluded): the pool, not the page. Counting stops at 10,000 (total_is_capped: true = at least that many). Under relevance the pool is companies with a description vector plus word matches, and only roughly the top 1,200 can be paged with q (600 for one seed alone): an empty page is the end of what you can reach, not of the pool, and paging can drift slightly. Under best_known / largest the pool is every company passing the filters, pageable to offset 10,000 with no repeats or skips. So total can differ with and without q; narrow with filters rather than paging deep.

total_is_capped
boolean
required

True when counting stopped at 10,000, so total (10,000) is a lower bound; false when total is exact.

already_yours
integer | null
required

How many of the companies counted in total your account already owns (has unlocked), so total − already_yours are new to you. Null when total_is_capped is true or total is null, when you own no companies yet, or for a token with no user.

Required range: x >= 0
results
object[]
required

The page, in sort order: one short card per company (id, name, website, one-line summary, industry, hq_location, states, employee_range, and matched_office when locality is set). Call lookup_company with an id for the full card. [] for limit: 0.

interpreted
object
required

What the search applied: always the sort, plus the expanded industry and city filters. Nothing is read out of q.

seeds_missing
string[]
required

The similar_to_many seeds (lowercased) that have no embedding, so they did not shape the results. [] when every seed was used or no seed list was sent.