Skip to main content
POST
Count matching leads

Authorizations

​
X-API-Key
string
header
required

Body

application/json

A search request.

Every query shape is accepted on every request and the record type picks which one is read, so the client can keep a draft of each while the user moves between the search types without losing what they typed.

Each field is named exactly for the record type that reads it. A stored search is re-run by rebuilding the request as {"record_type": rt, rt: query}, which only holds while that stays true.

​
record_type
enum<string>
required

Which dataset a search runs against, and so which provider serves it.

Values are persisted in String(16) columns, so every member must stay within 16 characters.

Available options:
people,
companies,
signal_companies,
signal_people,
lookalikes,
local_businesses,
hiring_companies,
backlinks,
search_results,
post_authors
​
backlinks
BacklinksQuerySchema · object | null

The sites linking to a domain or a page.

Name the target and get one row per referring site by default, sorted by the rank the link passes. Every attribute of a backlink the index can filter on is here, in four groups: the referring site, the referring page, the link itself, and the page it points at. The index takes at most eight filter conditions in one search, counting every value of every list as one; a ninth is refused rather than dropped.

​
companies
CompanyQuerySchema · object | null

Filters for a company search.

​
hiring_companies
HiringCompaniesQuerySchema · object | null

Filters for a search for companies with open roles matching a job title.

The rows are companies, one per employer, each carrying every open posting the search read for it. The count is of open postings, since the companies are folded from them once they are read.

​
local_businesses
LocalBusinessQuerySchema · object | null

Filters for a map search over business listings.

The one search here that asks "who is within this radius". Name a category, a business name or a website to look for, plus an area to look in for the radius part.

​
lookalikes
LookalikeQuerySchema · object | null

Filters for a search for companies resembling a set of seed companies.

​
people
PeopleQuerySchema · object | null

Filters for a people search.

​
post_authors
PostAuthorsQuerySchema · object | null

Filters for a search for people whose own LinkedIn posts carry a phrase.

The rows are people, one per author, each carrying every matching post the search read for them. The count is of posts, since the people are folded from them once they are read.

​
search_results
SearchResultsQuerySchema · object | null

Google searches to run, each landing the results Google shows for it.

Write each search the way you would type it into Google: operators (site:, intitle:, quoted phrases) work and cost nothing extra. One row is one result of one search, with the search that found it and its rank.

​
signal_companies
SignalCompaniesQuerySchema · object | null

Filters for a company buying-signal search.

​
signal_people
SignalPeopleQuerySchema · object | null

Filters for a person activity-signal search.

Response

Successful Response

How many leads matched, and the most one search may add.

​
max_rows_per_import
integer
required

The most rows one import adds for THIS organisation: the source's ceiling clamped by the plan's rows per table. Always a number, so anything quoting an import prices against this.

​
max_rows_per_search
integer | null
required

The data source's own ceiling on one search, before the plan. Null when the source has no ceiling of its own (the people and company searches) and the plan's rows per table is the only bound; a number on the searches whose rows are bought from a data source with a small pool.

​
row_order
enum<string>
required

Which matches one run keeps when more match than it can add. ranked means it keeps the closest matches, so the rows added are the best ones. recent means it keeps the newest. source_order means it keeps the first max_rows_per_import the search returns, which is not a quality order and should never be described as one. Worth showing whenever total is larger than max_rows_per_import, so a five-row sample can be read for what it is.

Available options:
ranked,
recent,
source_order
​
total
integer | null
required

How many leads match. Null when this search type has no live count: buying-signal searches are sold by the row and have no free tally behind them, so the only way to see what one finds is to preview it. Lookalike, map and technographic searches all do count.

​
at_capacity
boolean
default:false

Whether total is the most one run of this search can return rather than a real match count. True means at least that many match, so show the number as a floor (“100+ companies match”) and say that one run returns up to max_rows_per_import of them. False means total is the real tally, however far above the run limit it sits.

​
provider_notices
string[]

What qualifies this count, in the words to show beside it. A lookalike search with a minimum similarity fills this: the floor is applied to the matches once they arrive, after this count was taken, so the search can add fewer rows than total. Empty for every count that is exact.

​
supported
boolean
default:true

Whether counting is available for this search type. False means total is null for every set of filters, not just this one.