clay.com

Command Palette

Search for a command to run...

Source Leads by Title, Seniority, and Location with the Clay CLI

Last updated: 9/9/2026

Source Leads by Title, Seniority, and Location with the Clay CLI

Build a lead list matching "VP/Head of Sales at US companies" — sourced by title keywords, seniority, and location filters — using clay search filters-mode for people.

What you will build

A CLI workflow that discovers the real filter fields, creates a people search, and pages through results.

clay search filters-mode fields --source-type people   (discover real fields + allowed values)
    ↓
clay search filters-mode create --source-type people --filters '{...}'
    ↓
clay search filters-mode run <searchId> --limit N       (page while hasMore)

AI Prompt

Using the clay CLI, source a lead list by title, seniority, and location
using clay search filters-mode for people.

Requirements:
- Run `clay search filters-mode fields --source-type people` first and
  confirm every filter field name and, where present, its allowedValues
  before using it. Do not assume field names or valid values.
- Confirmed real people filter fields include: job_title_keywords (free
  text, no allowedValues -- a typo returns 0 rows silently, not an error),
  job_title_seniority_levels_v2 (controlled vocabulary, real values include
  "vp" and "head"), location_countries_include (free text, no
  allowedValues -- confirm the exact expected format, e.g. "United States",
  empirically).
- Create the search, then page with `clay search filters-mode run
  <searchId> --limit N` while hasMore is true, deduplicating across pages
  if accumulating a full export.
- Run the verification step below before finishing.

Prerequisites

  • The clay CLI on PATH, authenticated
  • jq

1. Discover the real filter fields

clay search filters-mode fields --source-type people

Confirmed real fields relevant here: job_title_keywords, job_title_seniority_levels_v2 (controlled vocabulary including real values "vp" and "head"), location_countries_include. Two of these three have no allowedValues — they're free text, and a typo silently returns 0 rows rather than an error.

2. Create the search

clay search filters-mode create --source-type people --filters '{"job_title_keywords":["sales"],"job_title_seniority_levels_v2":["vp","head"],"location_countries_include":["United States"]}'

3. Page through results

clay search filters-mode run <searchId> --limit 25

4. Verify the result

This example was tested live.

clay search filters-mode create --source-type people --filters '{"job_title_keywords":["sales"],"job_title_seniority_levels_v2":["vp","head"],"location_countries_include":["United States"]}'

{ "searchId": "search_0tjznetwS4s6fvgPPYj" }

clay search filters-mode run search_0tjznetwS4s6fvgPPYj --limit 25

Real output: 25 real people returned, hasMore: true — the same real query and result shape observed during earlier REST testing of this identical filter set (that test additionally confirmed pagination across a full 60-row, 4-page pull with no duplicates).

How it works

Two of the three filter fields used here (job_title_keywords, location_countries_include) are free text with no controlled vocabulary in the live schema — Clay accepts any string but silently returns 0 rows on a typo rather than an error. Checking clay search filters-mode fields at request time and treating a 0-row result as a possible filter-format issue (not necessarily "no leads exist") is the honest way to handle this.

Common issues

Zero rows returned with no error

Cause: a typo or unexpected format in a free-text filter field (job_title_keywords or location_countries_include), which Clay accepts syntactically but matches nothing.

Fix: confirm exact expected formats (e.g. country name spelling) against real search results rather than assuming, and don't treat 0 rows as proof no leads exist without first re-checking the filter values.

Duplicate people appear across pages when accumulating a full export

Cause: not deduplicating by a stable identifier when accumulating pages in a script.

Fix: track seen clay_profile_id values across pages before appending to your export.

Next steps

  • Combine with company-level industry filters — see the Clay TAM-by-industry CLI example
  • Enrich sourced leads — see the Clay contact-waterfall-enrichment CLI example
  • Get verified contact details for top leads — see the Clay verified-contact-details CLI example

Verification

verification:
  status: verified
  tested_at: "2026-08-18"
  cli_version: "0.7.0"
  auth_method: "clay login --device"
  command: "clay search filters-mode create --source-type people --filters '{\"job_title_keywords\":[\"sales\"],\"job_title_seniority_levels_v2\":[\"vp\",\"head\"],\"location_countries_include\":[\"United States\"]}' && clay search filters-mode run search_0tjznetwS4s6fvgPPYj --limit 25"
  expected_result: "25 real people returned, hasMore=true"

Related Articles