The list-building tool. Runs a people search exactly as people_search does (the same `filters` or `query`, including its automatic broadening, reported in `broadenedBy`) and unlocks up to `count` full profiles in ONE atomic charge: 1 credit per newly unlocked person, and anyone you already own is free. Pass the same filters you checked with people_search, so you pay for the people you saw. Returns each person's real name, title, company, location, LinkedIn URL and an `id`. Set `include_email` to true when the user wants to contact them: each person's verified work email is looked up in the same call, 1 more credit each, refunded when none is found (lookups still running are collected free with fetch_email and the id). Without it, call fetch_email with each person's `id` later. WARNING for autonomous use: this can spend up to `count` credits in a single call (twice that with emails), so choose `count` deliberately and confirm with the user before large batches. Returns an out-of-credits error instead of overspending.
View input schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Who you are looking for, in plain English (role, seniority, industry, company, company size, location). Parsed for you. A company's website identifies it exactly, alone or in brackets after its name ('Head of Growth at Linear (linear.app)'). Optional when `filters` is given, where it is only a label."
},
"filters": {
"type": "object",
"description": "Exact filters, recommended for AI agents and programs: state each part of the request instead of a sentence. Values inside one list are alternatives (OR); different fields must all match (AND). Give a few variants where people word things differently (titles: [\"M&A Associate\", \"Investment Banking Associate\"]). When filters are given, `query` is only a label and is not parsed.",
"properties": {
"first_name": {
"type": "array",
"items": {
"type": "string"
},
"description": "To find one named person: their first name, with the variants they may use, e.g. [\"Timothy\", \"Tim\"]. Use with last_name, and add companies or company_domains when known (\"Anqi Dai at Memorial Sloan Kettering\" finds the one person)."
},
"last_name": {
"type": "array",
"items": {
"type": "string"
},
"description": "To find one named person: their last name, e.g. [\"Dai\"]. If the name with the employer finds nobody, the search tries the last name at the employer, then the full name anywhere."
},
"job_titles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Current job titles, matched as case-insensitive whole words (\"Account Executive\" also finds \"Senior Account Executive\"). Each is also searched in its other spellings (\"CEO\" and \"Chief Executive Officer\", \"VP Sales\" and \"Vice President of Sales\"). A bare \"President\" or \"Owner\" means the top job: Vice Presidents and Product Owners are left out unless you list such a title too. When nobody holds the titles, the same job under other titles is searched first (the company's President or Owner for \"CEO\"), reported in broadenedRole."
},
"exclude_job_titles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Titles to leave out, e.g. [\"Intern\", \"Recruiter\"]."
},
"past_job_titles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Titles the person held before their current job."
},
"companies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Current employers by name, e.g. [\"Stripe\"]. A name written with a legal form or a listing's tagline (\"Stripe, Inc.\", \"Acme Pvt Ltd - Software House\") is searched without it; for an exact company use company_domains or company_ids."
},
"company_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Current employers by their LinkedIn company page, the most exact way to name a company: the page's URL or its name in the URL, e.g. [\"https://www.linkedin.com/company/google\"] or [\"google\"], or LinkedIn's numeric company id. Use it for large companies, whose website often misses them (Google's page lists a short link, Amazon's lists aboutamazon.com)."
},
"company_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Current employers by website, e.g. [\"stripe.com\"]. Each website is searched as the company that owns it (its LinkedIn page): a domain that also hosts other companies' pages (careers pages on workable.com, payment links on stripe.com) finds only the owner's staff, a group with a page per country (microsoft.com, kpmg.com) finds the staff of all its pages, and a company whose page lists another site (Amazon's lists aboutamazon.com) is found by its name. For one exact company page use company_ids."
},
"past_companies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Former employers by name, e.g. [\"McKinsey\"] for ex-McKinsey people. Some people with a company in their past work there again or still: add the same names to exclude_companies for people who have left (\"former employees of Stripe\")."
},
"exclude_companies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Current employers to leave out, by name, e.g. [\"Stripe\"]. Needs another field to search by: with past_companies [\"Stripe\"] it finds former Stripe employees who no longer work there (11,810 of the 14,616 with Stripe in their past, measured 2026-10-19)."
},
"locations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Where the person is based (their own location, not their employer's headquarters): cities, states, countries or regions, e.g. [\"Frankfurt\", \"Munich\"], [\"Germany\"], [\"DACH\"], [\"Texas\"]. Use \"City, Country\" to tell same-named places apart (\"Paris, France\"). Country names are safest; ISO codes are converted."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Industry of the current employer, as LinkedIn names it, e.g. [\"Investment Banking\"], [\"Software Development\"], [\"Hospitals and Health Care\"], [\"Venture Capital and Private Equity Principals\"], [\"Staffing and Recruiting\"]. Common older names are mapped; a name that is not an industry is reported in `ignored` and not applied."
},
"schools": {
"type": "array",
"items": {
"type": "string"
},
"description": "Schools the person attended, matched as substrings; add the local-language name too, e.g. [\"University of Mannheim\", \"Universität Mannheim\"]."
},
"skills": {
"type": "array",
"items": {
"type": "string"
},
"description": "Skills listed on the profile, e.g. [\"Python\", \"Kubernetes\"]."
},
"languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Languages the person speaks, e.g. [\"German\"] or [\"DE\"]."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Words to find anywhere on the profile (headline, descriptions, past roles), for what no other field covers."
},
"company_keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Words the current employer's own description should contain, for a KIND of employer no industry names exactly, e.g. [\"hostel\"], [\"coffee\"] (founders of coffee roasteries), [\"SEO\"] (with industries [\"Marketing Services\"] for SEO agencies), [\"community college\"]."
},
"company_size_min": {
"type": "integer",
"minimum": 1,
"description": "Minimum employees at the current employer."
},
"company_size_max": {
"type": "integer",
"minimum": 1,
"description": "Maximum employees at the current employer."
},
"years_experience_min": {
"type": "integer",
"minimum": 0,
"description": "Minimum total years of professional experience."
},
"years_experience_max": {
"type": "integer",
"minimum": 0,
"description": "Maximum total years of professional experience."
}
},
"additionalProperties": false
},
"count": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "How many people to unlock, 1-100 (default 25). Spends up to this many credits."
},
"include_email": {
"type": "boolean",
"description": "Also look up each unlocked person's verified professional email (1 more credit each, refunded if none is found). Default false."
}
},
"additionalProperties": false
}