--- title: "Search for People" method: POST path: "/search_people" tags: ["Search"] --- # Search for People `POST /search_people` ## Request - Base URL: `https://api.moltsets.com/api/v1/tools` - URL: `https://api.moltsets.com/api/v1/tools/search_people` - Auth: HTTP bearer The People Search API lets you search MoltSets' contact database for people by name, job title, company, industry, country, seniority, or department. Use `title` for the job title or role — it matches the title field alone, so it is far more precise than putting a role in `query`. Use `query` for the person's name, or for loose natural-language phrases when you have nothing more specific. To find people at a specific company, use `company` (company name) or `company_domain` (website domain) rather than putting the employer in `query`. Use the exact filters (`country`, `state`, `city`, `seniority`, `industry`, `department` or `functional_area`, `employee_range`, `revenue_range`) to narrow further — `employee_range` and `revenue_range` scope to people at companies of that size or revenue without needing a specific company. Combining `query` with filters gives the most precise matches. Every result comes back ranked, with a higher `_score` meaning a stronger match. Every positive filter accepts either a single value or a list of values. A list is OR within its field and AND across fields, so `title: ["CEO", "CMO"]` with `country: ["United States", "Canada"]` means (CEO or CMO) in (United States or Canada) — one search instead of one per value, with every match ranked together. The `exclude_*` parameters (`exclude_company_domain`, `exclude_country`, `exclude_state`, `exclude_industry`, `exclude_seniority`, `exclude_employee_range`) work the other way round: each one also takes a list, but removes matches rather than selecting them. `exclude_company_domain` is how you suppress companies you already have. Exclusions narrow a search but cannot be the whole search — you still need at least one positive input. **Use this endpoint to:** - Build targeted lead lists for outbound sales - Identify decision makers at specific target accounts - Populate outbound sequences with verified contact data **Fair Use Policy:** This API is subject to our Fair Use Policy for Search. **Outcomes:** A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name. ## Headers - `User-Agent` string, required ## Request body - object - `query` string: Full-text search across full_name, first_name, last_name, company name, title (~85% filled), and headline (~65% filled) using cross-field matching. Multi-word queries distribute terms across fields — "John Smith" matches first_name: John AND last_name: Smith rather than requiring either field alone to contain the full string. Best for person names, and for loose natural-language phrases when nothing more specific fits. For a job title or role, use the `title` filter instead: a role placed here is diluted across names and company names and only needs most of its terms to match, so "Account Executive" in `query` can also return Account Managers. Likewise use `seniority` for level (VP, Director, C-suite), and `company` or `company_domain` for a specific employer. Categorical values like country or seniority belong in their own filter params rather than this field. - `title` union: Job title filter (~85% filled) — scopes results to people whose job title matches, and the precise way to search by role. The match is analysed rather than literal: a one or two word title requires every word, so "Account Executive" will not return Account Managers. A longer title requires 75% of its words, rounded down — a three or four word title must match all but one, a five or six word title all but two. That allowance is what stops function words breaking a match, so "VP of Sales" still finds "VP, Sales". Extra words in the stored title are always fine: "Account Executive" matches "Senior Account Executive, SMB". Prefer this over putting a role in `query`. For seniority level use the `seniority` filter, which is a clean enumerated list, and use `title` for the role or function itself — the two combine, e.g. `title: "Sales"` with `seniority: "VP"`. Around 15% of profiles carry no title at all, and those can never match a title filter. Accepts a single value or a list — a list matches any of its values (OR), so `title: ["CEO", "CMO"]` returns records matching either. - string - string[] - `company` union: Company name filter — scopes results to people whose employer's name matches. Analysed match: every word you provide must appear in the company name, so extra words in the stored name are fine ("Acme" matches "Acme Corporation"). Use this when you have a company name but not its domain; if you have the domain, prefer `company_domain`, which is more precise. Accepts a single value or a list — a list matches any of its values (OR), so `company: ["Acme", "Globex"]` returns records matching either. - string - string[] - `company_domain` union: Company domain filter — scopes results to people at the company with this website domain. Full URLs are normalised automatically ("https://www.acme.com/about" → "acme.com"), so there is no need to strip the protocol or path yourself. The most precise way to target a single company — prefer it over `company` whenever you know the domain. Accepts a single value or a list — a list matches any of its values (OR), so `company_domain: ["acme.com", "stripe.com"]` returns records matching either. A list can hold up to 100 domains. - string - string[] - `country` union: Exact country name filter (~99% filled — most reliable filter). Must match the stored value exactly. Top values by volume: "United States", "India", "United Kingdom", "Brazil", "Canada", "France", "Mexico", "Australia", "China", "Spain", "Netherlands", "Italy", "Indonesia", "Germany", "Philippines", "Turkey", "South Africa", "Saudi Arabia", "Argentina", "Singapore", "United Arab Emirates", "Colombia", "South Korea", "Malaysia", "Poland", "Belgium", "Switzerland", "Ireland", "Sweden", "Denmark", "Norway", "Austria", "Portugal", "Israel", "New Zealand", "Finland", "Greece", "Hungary", "Romania", "Ukraine". Use the full English country name. "UK" and "HK" also exist in the data as dirty values — prefer "United Kingdom" and "Hong Kong". Accepts a single value or a list — a list matches any of its values (OR), so `country: ["United States", "Canada"]` returns records matching either. - string - string[] - `state` union: Exact state or region name filter on the person's location. Accepts the full name with standard capitalisation or its abbreviation — "Texas" and "TX" both work. Canadian provinces match by their two-letter code too — "Ontario" or "ON", "British Columbia" or "BC", "Quebec" or "QC". Combine with `country` for precision. Accepts a single value or a list — a list matches any of its values (OR), so `state: ["Texas", "Florida"]` returns records matching either. - string - string[] - `city` union: Exact city name filter on the person's location. Must match the stored value exactly, with standard capitalisation. City names repeat across regions, so combine with `state` and/or `country` to disambiguate — e.g. city: "Portland", state: "Oregon". Matches only the exact stored city, not its suburbs — for a metro-area search prefer `state` or `country`. Accepts a single value or a list — a list matches any of its values (OR), so `city: ["Austin", "Dallas"]` returns records matching either. - string - string[] - `seniority` union: Exact seniority level filter (~60% filled). Must match one of the enumerated values exactly, including the space in "C Suite" (not a hyphen). Accepts a single value or a list — a list matches any of its values (OR), so `seniority: ["VP", "C Suite"]` returns records matching either. - 'Intern' | 'Entry' | 'Senior' | 'Manager' | 'Director' | 'VP' | 'Head' | 'C Suite' | 'Owner' | 'Partner' - string[] - `industry` union: Exact current industry filter (~60% filled). These 22 buckets are the only supported values, and must match exactly, including capitalisation and punctuation (e.g. the ampersand in "Marketing & Advertising"). Accepts a single value or a list — a list matches any of its values (OR), so `industry: ["Information Technology", "Finance and Banking"]` returns records matching either. - 'Professional and Business Services' | 'Information Technology' | 'Manufacturing' | 'Retail' | 'Health and Pharmaceuticals' | 'Creative Arts and Entertainment' | 'Construction' | 'Marketing & Advertising' | 'Finance and Banking' | 'Tourism and Hospitality' | 'Non-Profit and Social Services' | 'Food and Beverage' | 'Real Estate' | 'Education' | 'Transportation and Logistics' | 'Media and Publishing' | 'Energy' | 'Government and Public Administration' | 'Automotive' | 'Telecommunications' | 'Agriculture' | 'Utilities' - string[] - `department` union: Exact department filter (~60% filled). Shares its underlying data with `functional_area` — use one or the other, not both. Must match one of the enumerated values exactly, including capitalisation and punctuation (e.g. the ampersand in "Medical & Health"). Accepts a single value or a list — a list matches any of its values (OR), so `department: ["Sales", "Marketing"]` returns records matching either. - 'Operations' | 'Sales' | 'Information Technology' | 'Education' | 'Engineering' | 'Finance' | 'Medical & Health' | 'Marketing' | 'Human Resources' | 'Design' | 'Consulting' | 'Legal' - string[] - `functional_area` union: Exact functional area filter (~60% filled). Shares its underlying data with `department` — use one or the other, not both. Accepts a single value or a list — a list matches any of its values (OR), so `functional_area: ["Sales", "Marketing"]` returns records matching either. - 'Operations' | 'Sales' | 'Information Technology' | 'Education' | 'Engineering' | 'Finance' | 'Medical & Health' | 'Marketing' | 'Human Resources' | 'Design' | 'Consulting' | 'Legal' - string[] - `employee_range` union: Exact employee-count range filter on the person's current employer — finds people at companies of a certain size without needing to name a specific company. These eight numeric bands are the only supported values, and use the same vocabulary as `search_companies`. Combine with other filters, e.g. `seniority: "VP"`, `employee_range: "51-200"`. Accepts a single value or a list — a list matches any of its values (OR), so `employee_range: ["51-200", "201-500"]` returns records matching either. - '1-10' | '11-20' | '21-50' | '51-200' | '201-500' | '501-1000' | '1001-5000' | '5001+' - string[] - `revenue_range` union: Exact annual revenue range filter on the person's current employer — finds people at companies of a certain revenue without needing to name a specific company. These seven bands are the only supported values, and use the same vocabulary as `search_companies`. "Above $50M" is a flat catch-all for all revenue over $50M; there is no finer band above it. Accepts a single value or a list — a list matches any of its values (OR), so `revenue_range: ["$10M - $20M", "$20M - $50M"]` returns records matching either. - 'Below $500k' | '$500k - $1M' | '$1M - $5M' | '$5M - $10M' | '$10M - $20M' | '$20M - $50M' | 'Above $50M' - string[] - `naics_code` union: Exact NAICS industry code filter on the person's current employer (~50% filled). Works at any level of the hierarchy, from the 2-digit sector ("23" = Construction, "54" = Professional Services) through to the 6-digit national industry ("541120" = Offices of Notaries, "511210" = Software Publishers). Use a short code for broad industry targeting and a longer code for precision. The most standardised industry filter available — prefer it over `industry` when you need fine-grained targeting. Accepts a single value or a list — a list matches any of its values (OR), so `naics_code: ["5112", "5415"]` returns records matching either. - string - string[] - `linkedin_industry` union: Exact LinkedIn industry label filter on the person's current employer. Uses LinkedIn's own industry vocabulary, which is far finer-grained than the 22 buckets in `industry`. Must match the stored label exactly, with standard capitalisation — for example "Software Development", "Hospitality", "Legal Services", "Wellness and Fitness Services", "Construction", "Staffing and Recruiting". Use when a niche industry cannot be expressed by the broad `industry` buckets. Accepts a single value or a list — a list matches any of its values (OR), so `linkedin_industry: ["Software Development", "IT Services and IT Consulting"]` returns records matching either. - string - string[] - `exclude_company_domain` string[]: Company domains to exclude. People at any listed company are dropped from the results — this is the suppression list, so pass the accounts you already have (existing customers, current vendors, your own company) and they never come back. Full URLs are normalised automatically, exactly as with `company_domain`. Excluded records cost you nothing: they consume no tokens and no fair use records, so excluding here is always cheaper than filtering the results yourself. A list can hold up to 100 domains. - `exclude_country` string[]: Countries to exclude. People in any listed country are dropped. Accepts the same values as `country` — use it when you want everywhere except a few places. - `exclude_state` string[]: States or regions to exclude. People in any listed state are dropped. Accepts the same values as `state` (full names or abbreviations). Combine with a positive `country` — for example `country: "United States"` with `exclude_state: ["California"]`. - `exclude_industry` string[]: Industries to exclude. People whose current industry is any listed value are dropped. Accepts the same values as `industry`. Around 40% of profiles carry no industry at all, and exclusion only removes profiles that positively carry a listed value — so those profiles still appear. - `exclude_seniority` string[]: Seniority levels to exclude. People at any listed level are dropped. Accepts the same values as `seniority` (note the space in "C Suite"). Same caveat as `exclude_industry`: profiles with no seniority on record are not excluded. - `exclude_employee_range` string[]: Employer size bands to exclude. People at companies in any listed band are dropped. Accepts the same values as `employee_range` — for example ["1-10", "11-20"] to skip very small companies, or ["5001+"] to skip enterprises. - `limit` integer: Number of results to return (default: 10, max: 25). - `offset` integer: Number of results to skip for pagination (default: 0). Use with limit to page through results — e.g. offset: 10 to get the second page of 10 results. ## Response `200` Success ## Other responses - `401`: Unauthorized - `402`: Payment Required — insufficient tokens - `403`: Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive - `422`: Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values - `429`: Too Many Requests — rate limit, Fair Use window exhausted, or too many concurrent searches - `500`: Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically. --- [API](https://skmtc.dev/moltsets/apis/moltsets-api.md) - [All operations](https://skmtc.dev/moltsets/apis/moltsets-api/llms.txt) - [OpenAPI document](https://skmtc.dev/moltsets/apis/moltsets-api/revisions/b116df68bd90?raw)