Filters

Describe the audience you want.

The named filter keys, listed in our column order rather than in include and exclude pairs. A list key is OR inside and AND across keys. An exclude_* key is the NOT of its twin. A range key comes as a _min / _max (inclusive) or _after / _before (exclusive) pair. A null column never matches a value key. Flat keys cover includes, ranges and the six common negations. Everything else goes through where with not_in.

Named keys

Key	Type	Description
`countries`	array of Country	Contact countries to include. Send ISO-2 codes such as us, or English names such as Germany.
`exclude_countries`	array of Country	Contact countries to exclude. Send ISO-2 codes such as us, or English names such as Germany.
`has_linkedin`	boolean	True keeps only contacts that carry a LinkedIn URL.
`has_work_email`	boolean	True keeps only contacts that carry a work email.
`has_phone`	boolean	True matches contacts with a mobile or direct phone. False matches contacts without either.
`include_secondary_roles`	boolean	By default, filters match a person's main role. Set include_secondary_roles to true to also match their other current roles; the contact's top-level fields still show the main role.
`title_query`	string or array of string	Words in the current title. The match is case-insensitive and uses whole words: 'CTO' matches 'Co-founder & CTO' but not 'Director'. The words also match across punctuation: 'VP Sales' also matches 'VP, Sales' and 'VP-Sales'. Send an array to match any one of several phrases, for example ["VP Sales", "Vice President of Sales"]. A phrase that is blank after trimming answers 400 request.invalid. A leading or trailing wildcard answers 422 filter.rejected. For a substring match, use `where` with the `contains` operator on `title`.
`functions`	array of JobFunction	Job functions to include.
`exclude_functions`	array of JobFunction	Job functions to exclude.
`seniority`	array of Seniority	Seniority rungs to include.
`exclude_seniority`	array of Seniority	Seniority rungs to exclude.
`domains`	array of string	Current employer domains. A full URL reduces to a bare domain on input.
`exclude_domains`	array of string	Current employer domains to exclude.
`company_names`	array of string	Current employer names. Case-insensitive exact match after normalization. Lowercase, trim and collapse whitespace. Strip one trailing legal suffix with an optional comma, then a leading "the ". Legal suffixes: inc, inc., incorporated, llc, l.l.c., ltd, ltd., limited, corp, corp., corporation, co, co., gmbh, ag, sa, s.a., bv, b.v., plc, pty ltd, srl. An empty normalized name returns 400 request.invalid. Values are OR within this key and AND across keys.
`exclude_company_names`	array of string	The NOT of company_names after the same normalization. Lowercase, trim and collapse whitespace. Strip one trailing legal suffix with an optional comma, then a leading "the ". Legal suffixes: inc, inc., incorporated, llc, l.l.c., ltd, ltd., limited, corp, corp., corporation, co, co., gmbh, ag, sa, s.a., bv, b.v., plc, pty ltd, srl. An empty normalized name returns 400 request.invalid. Values are OR within this key and AND across keys.
`company_size`	array of CompanySize	Company employee bands to include.
`company_revenue`	array of CompanyRevenue	Company revenue ranges to include. Only companies with a known revenue range match; most small companies have none, so this key leaves them out.
`industries`	array of Industry	Company industries to include, as slugs such as software_development. A label such as 'Software Development' or 'IT Services & IT Consulting' is folded to its slug. Read the values from GET /contacts/schema/industries/values.
`exclude_industries`	array of Industry	Company industries to exclude, as slugs such as software_development. A label such as 'Software Development' or 'IT Services & IT Consulting' is folded to its slug. Read the values from GET /contacts/schema/industries/values.
`schools`	array of string	School names. It matches any school on the record. The match is exact on the stored value, so send the name as the record holds it.
`skills`	array of string	Skill names. It matches any skill on the record. The match is exact on the stored value, which is lowercase, and the input is lowercased. Read the values from GET /contacts/schema/skills/values.
`employee_count_min`	integer	The smallest company employee count, inclusive.
`employee_count_max`	integer	The largest company employee count, inclusive.
`founded_year_min`	integer	The earliest company founding year, inclusive.
`founded_year_max`	integer	The latest company founding year, inclusive.
`company_hq_countries`	array of Country	Company headquarters countries to include. Send ISO-2 codes such as us, or English names such as Germany.
`last_round_after`	YearMonth	The latest financing event is after this month, exclusive.
`last_round_before`	YearMonth	The latest financing event is before this month, exclusive.
`last_round_types`	array of FundingRoundType	Types of the latest financing event to include.
`total_funding_min`	integer	The smallest total funding in US dollars, inclusive. Missing funding is null and never matches.
`total_funding_max`	integer	The largest total funding in US dollars, inclusive.
`company_ids`	array of CompanyId	Company ids (`com_`) of the current employer to include. Take them from `POST /companies/search` or `POST /companies/lookup`. Values are OR within this key and AND across keys. Takes up to 1,000 ids.

Closed lists

Send the slug, in monospace below. A value outside the list is rejected.

Seniorityfrozen

The seniority rung of the contact. The list is frozen. A C-level person whose title names a founder, owner or partner role is founder_or_partner; add it to reach founder CEOs.

c_levelvpdirectormanagersenior_icentryfounder_or_partnerunknown

JobFunctionfrozen

The job function of the contact's main job. The list holds 21 values. operations: running the business day to day: operations, facilities, administration. general_management: business leadership, general management, strategy and consulting. sales_and_bizdev: selling, account management, partnerships and business development. information_technology: IT, systems, infrastructure, data and support for technology. education: teaching, instruction, academic and school roles. healthcare_and_social_services: clinical, nursing, care and social service roles. finance_and_accounting: finance, accounting, treasury and audit. manufacturing_and_production: making things: production, plant and manufacturing roles. engineering: software, hardware and other engineering roles. customer_service: customer service, support and customer success. government_and_public_safety: public administration, government, police, fire and military. marketing_and_advertising: marketing, advertising, brand and growth. human_resources: recruiting, people operations, compensation and training. arts_and_creative: design, art, culture and other creative work. construction_and_trades: construction, building and skilled trades. legal: lawyers, legal counsel, compliance and regulatory work. supply_chain_and_logistics: supply chain, logistics, transport and warehousing. procurement: purchasing and procurement. writing_and_editorial: writing, editing, journalism and publishing. research_and_science: research and development, laboratory and scientific roles. other: a function the source does not name.

operationsgeneral_managementsales_and_bizdevinformation_technologyeducationhealthcare_and_social_servicesfinance_and_accountingmanufacturing_and_productionengineeringcustomer_servicegovernment_and_public_safetymarketing_and_advertisinghuman_resourcesarts_and_creativeconstruction_and_tradeslegalsupply_chain_and_logisticsprocurementwriting_and_editorialresearch_and_scienceother

EmailStatusfrozen

The work email status comes from our data source; verified_at is the month the source last verified the address. The list is frozen.

unknownvalidinvalidcatch_all

CompanySizefrozen

The employee band of the company. The list is frozen.

1-1011-5051-200201-500501-1K1K-5K5K-10K10K+

FundingRoundTypefrozen

The eight funding categories. Series C and later rounds use series_c_plus.

pre_seedseedseries_aseries_bseries_c_plusprivate_equitydebtother

Signalfrozen

The five contact signals. One year at the current company, a new role within 90 days, a recent employer change, a founder role, or employment at a public company. Filter on signals with in or not_in inside where.

one_year_at_companynew_in_role_90drecent_job_changefounderat_public_company

Countryfrozen

A country as a lowercase ISO-2 slug, for example us or de. Aliases normalize on input: US, USA and United States all become us. Unknown values return 400 filter.unknown_value with allowed values and a hint to GET /contacts/schema/country/values.

Industry

A company industry slug. Read the allowed values from GET /contacts/schema/industries/values.

Read the values from /contacts/schema/industries/values.

The where tree

The condition tree. It is opened per account when the named keys cannot express the audience. The signals column is filtered here, with in or not_in.

One node of the condition tree: a group (and, or, not) or a leaf. The tree is at most 4 deep, holds at most 25 leaves, and takes at most 50 values in one in. An and or or group needs at least one child. A tree over 32 predicates, or a leaf with a leading wildcard, is rejected with 422 filter.rejected. A refused operator, value type or shape answers 422 filter.rejected and names what the column takes. Fields resolve against GET /contacts/schema, case-insensitively, and an unknown field returns 400 filter.unknown_key. A closed-list value in a where leaf folds its aliases, as a named key does, and an unknown value answers 400 filter.unknown_value.

Operators: eqneqinnot_ingtgteltltecontainsexists.

Skills carry no flat negation. Exclude them with not_in inside where.

Exclude a skill

{
  "where": {
    "field": "skills",
    "op": "not_in",
    "value": [
      "cold calling"
    ]
  }
}

Paging a search

Search answers with one page. Pass page.next_cursor back unchanged on the next call, and stop when it is null.

Read every page

const filter = { countries: ["us"], seniority: ["vp"] };
const rows = [];
let cursor = null;

do {
  const response = await fetch("https://api.leadmcp.ai/v1/contacts/search", {
    method: "POST",
    headers: { Authorization: "Bearer lm_live_YOUR_API_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ filter, limit: 50, cursor }),
  });
  const body = await response.json();
  rows.push(...body.data);
  cursor = body.page.next_cursor;
} while (cursor !== null);

To deliver a list, start an export instead of paging search.

Aliases

The API normalizes these on input.

A full URL reduces to a bare domain on input.
Aliases normalize on input: US, USA and United States all become us.
An empty normalized name returns 400 request.invalid.
Matching is exact: an email is lowercased and a LinkedIn URL reduces to its slug.
The match is exact on the stored value, which is lowercase, and the input is lowercased.

Stated limits

A history key matches any entry on the record. The schools key matches any school. The skills key matches any skill.
Past employers are not in the data: experience lists current roles only, main role first. Filter titles with title_query.
A null column never matches a value key. Use has_work_email, has_phone and has_linkedin to ask for presence.
Signals have no flat key. Filter them with in or not_in on signals inside where.

Docs for agents: llms.txt