Skip to main content
POST
Create a table from a lead search

Authorizations

​
X-API-Key
string
header
required

Body

application/json

A search plus a new table to put its results in.

​
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.

​
enrichments
enum<string>[]

What to find out about the rows this search adds. Optional on a paid finder. Find People and Find Companies require at least one. Each becomes its own column, and each is billed per row that comes back with an answer.

Maximum array length: 4

An enrichment offered at import, in the user's vocabulary not the catalog's.

Each option names an outcome and resolves to the curated enrichment that delivers it, so importing leads stays a question about what you want rather than about who supplies it.

Kept as its own enum rather than reusing the capability keys directly: the import page offers a deliberately short list, and which enrichments belong on it is a product decision that should not change every time the catalog gains a capability.

Available options:
find_email,
find_phone,
enrich_contact,
enrich_company
​
folder_id
string<uuid> | null

The folder to make the new table in, as when the search was started from inside one on the Tables list. Leave it out for the top level.

​
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.

​
include_people_already_in_tables
boolean
default:false

A people search only. By default it leaves out the people who already have a row in one of the workspace's other tables, and keeps looking until enough new people are added; the response says how many it skipped. Set true to add them again.

​
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.

​
row_limit
integer | null

Rows to add. Clamped further by the organisation's plan cap; omit for the maximum.

Required range: 1 <= x <= 1000000
​
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.

​
table_name
string | null

The new table's name. Omit it and the table is named after the search, the name POST /find-leads/suggest-table-name/ gives.

Required string length: 1 - 255

Response

Successful Response

The table a search produced.

​
rows_created
integer
required
​
table_id
string<uuid>
required
​
table_name
string
required
​
total_matched
integer
required
​
earlier_table
EarlierLeadTableSchema · object | null

A table the same search (the same filters) already built, when it still exists.

​
enrichments_applied
enum<string>[]

Chosen enrichments that became a column on the new table.

An enrichment offered at import, in the user's vocabulary not the catalog's.

Each option names an outcome and resolves to the curated enrichment that delivers it, so importing leads stays a question about what you want rather than about who supplies it.

Kept as its own enum rather than reusing the capability keys directly: the import page offers a deliberately short list, and which enrichments belong on it is a product decision that should not change every time the catalog gains a capability.

Available options:
find_email,
find_phone,
enrich_contact,
enrich_company
​
enrichments_skipped
enum<string>[]

Chosen enrichments that could not run against the records this search returned. Leads with no LinkedIn URL cannot be enriched from one. The table is still created.

An enrichment offered at import, in the user's vocabulary not the catalog's.

Each option names an outcome and resolves to the curated enrichment that delivers it, so importing leads stays a question about what you want rather than about who supplies it.

Kept as its own enum rather than reusing the capability keys directly: the import page offers a deliberately short list, and which enrichments belong on it is a product decision that should not change every time the catalog gains a capability.

Available options:
find_email,
find_phone,
enrich_contact,
enrich_company
​
import_status
enum<string>
default:success

running when the request added a first batch and the rest is still being added in the background, so poll the table's search runs for progress; success when every row is in.

Available options:
running,
success,
failed
​
people_skipped
integer
default:0

People the request left out because another of the workspace's tables already has them. A run that continues in the background goes on skipping them.

​
provider_notices
string[]

What the data source said about the rows it sold, in its own words; see the preview response. Empty for every data source that attaches nothing.

​
rows_not_added
RowsNotAddedSchema · object | null

The people the search found that are not rows, and why, once every row is in: found_twice when the people search holds one person under two records, so a new table took them once; already_in_table when a person found was already a row of the table. Null when every person found was added, or while rows are still being added.

​
rows_wanted
integer
default:0

Rows the import set out to add in all.

​
run_id
string<uuid> | null

The run row recording this import, when the search is persisted.

​
skip_limit_reached
boolean
default:false

Whether the search stopped looking after skipping as many people as one search may, so fewer rows may be added than asked for.

​
table_run_request_id
string<uuid> | null

The request for the table run that fills the new table's columns, when every row was added by this request: the run is minted with it as its origin. Null while rows are still being added in the background, where each batch fills its own.