Skip to main content
POST
Search Leads Finder
Search for people using person and company filters. This operation uses a filters object and zero-based page pagination. Find people uses a different query model and cursor pagination; their request bodies are not interchangeable.
The limit is 5 requests per second per workspace. Each returned lead costs 0.1 credits; empty pages cost zero credits. At least 0.1 credits must be available before searching; credit admission can reserve up to size × 0.1 credits before the request runs.

​
Choose filters

At least one non-empty filter other than searchMode is required. Include only the criteria you need. The OpenAPI request schema below lists the supported fields. Use strings or arrays for job, jobExclude, company, companyUrl, person locations, and job functions. Other text filters accept strings; separate multiple values with newlines. Each job-function include/exclude input allows at most 300 non-empty values. searchMode supports SMART, WORD, and STRICT, defaulting to SMART. Textual tenure examples include 1 to 2 years, Less than 1 year, and More than 10 years. Structured duration accepts latestCompany, currentCompany, previousCompany, latestJob, currentJob, previousJob, and total. Each contains min, max, or both, with non-negative integer year and/or month values; months must be 0–11 and the minimum must not exceed the maximum. Structured bounds override the corresponding textual tenure field.
Structured tenure example

​
Expected filter values

These values apply to POST /v1/leads-finder and the airscale_leads_finder MCP tool. Find Companies filter values belongs to a different search and does not list Leads Finder values. Use the identifiers below for preset filters. Include and exclude fields use the same vocabulary. For string fields, separate multiple values with a newline (\n in JSON). jobFunction and jobFunctionExclude also accept arrays, with at most 300 values in each field. Use exact job-function identifiers, such as business_development, rather than display labels such as Business Development.
Some unsupported legacy values can be ignored instead of rejected. A successful response does not confirm that every supplied filter value was applied. Use the values and formats documented here.

​
Seniority

For seniority and seniorityExclude, use these 12 values:
Example: "seniority": "c_suite\nvp\ndirector".

​
Job function

For jobFunction and jobFunctionExclude, use an identifier from the full list below. Common examples are sales, business_development, software_development, demand_generation, human_resources, and accounting.
Job-function example

​
Funding round

For funding, use these 30 values:
Example: "funding": "SEED\nSERIES_A". Use fundingAmount for a last-funding amount range and fundingDateMonths for the lookback period; these are separate fields described below.

​
Company type

For type and typeExclude, use:

​
Profile badge

For profileBadge, use:

​
Search mode

For searchMode, use SMART, WORD, or STRICT. The default is SMART. This controls text matching; it does not turn arbitrary text into a supported preset identifier.

​
Department headcount and growth

department combines a department identifier and a headcount range on separate lines. growth combines a department identifier, a percentage range, and a lookback period on separate lines. Use 1 month, 3 months, 6 months, or 12 months for the growth period. The default is three months; other periods currently fall back to three months. These metrics use the following 27 department identifiers, a smaller list than the person job-function catalogue:

​
Ranges and dates

These fields take strings rather than preset identifiers. Use plain numbers without currency symbols or thousands separators. The tenure presets are Less than 1 year, 1 to 2 years, 3 to 5 years, 6 to 10 years, and More than 10 years. Custom continuous ranges such as "2 to 4 years" are also supported. If you combine tenure ranges, use adjacent ranges without gaps. For month-level bounds, use the structured duration fields described above. The company-size presets are 1-10, 11-20, 21-50, 51-100, 101-200, 201-500, 501-1000, 1001-2000, 2001-5000, 5001-10000, and 10000+. Custom numeric ranges are also supported.

​
Text and location filters

These fields accept search text rather than a closed preset list. The examples are starting points, not the only accepted values.
Preset-filter example

​
Read results and paginate

The response contains rows, total, page, and size. Each row is a nested person record with snake_case keys: the name is under profile (profile.first_name, profile.last_name, profile.headline), the LinkedIn URL is link.linkedin, work history is position_groups, and the current employer is company (company.summary.name, company.link.domain). Fields depend on available data, can be null or absent, and rows can include fields not listed in the schema. total can be null when a reliable count is unavailable or company/title correlation removes rows. size defaults to 50 and accepts 1–100. Start at page: 0 and increment the page while keeping the same filters and size. This operation does not return next_cursor. When company and title filters are combined, returned rows are checked for a matching title at the identified company; a page can contain fewer rows after that check, and a short page alone does not establish exhaustion. After 429, retry in a later second with bounded exponential backoff. For 503, retry with increasing delays and a fixed retry limit; contact support if errors persist. Correct invalid filters before retrying 400 responses. Requests larger than 256 KiB return 413.

​
Next step

Use Find people if you need its person/current-company/past-experience filter model and free count operation. Existing Leads Finder integrations can continue using their documented route and request model.

Authorizations

​
Authorization
string
header
required

Use an Airscale workspace API key. Never expose the key in client-side code.

Body

application/json
​
filters
object
required

At least one non-empty filter other than searchMode is required. Use only the documented fields; some malformed legacy values are ignored by the runtime rather than rejected.

​
page
default:0
Required range: x >= 0
​
size
default:50
Required range: 1 <= x <= 100

Response

A page of public lead records. No cursor is returned.

​
rows
object[]
required

Nested person records with snake_case keys (for example profile.first_name, link.linkedin, position_groups). Fields vary per record and may be null.

​
total
number | null
required

May be null when a reliable total is unavailable or company/title correlation removes rows.

​
page
integer
required
​
size
integer
required