--- title: "Find Prospects" method: POST path: "/mcp/tools/find_prospects" tags: ["mcp"] --- # Find Prospects `POST /mcp/tools/find_prospects` ## Request - Base URL: `https://api.iridiumhqmcp.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.iridiumhqmcp.com/mcp/tools/find_prospects` - Auth: HTTP bearer Find people on LinkedIn and, optionally, verify and write to a few of them — one tool that spends only what the filters you asked for actually cost. USE THIS as the default for any "find me people who..." request. It searches once, narrows for free on the fields the search already returned, and opens full profiles only for the number you allow, best candidates first. **This is the tool that answers "who actually HAS the #hiring badge / the #opentowork badge".** Set `hiring` or `open_to_work` and give it `max_touches`: it orders the bucket by the free signals most likely to carry the badge, opens that many profiles — the only place the badge exists — and tells you which candidates it CONFIRMED. Cost is 1 profile touch per candidate confirmed, except that a full Recruiter seat confirms "open to work" for free at search time. Read `confirmed` and each candidate's `confirmed` / `badges` to see who is verified; the rest of the bucket is unverified and the response says so. Four phases, and you control where it stops: max_touches=0 (default) search + free narrowing only. No profile is opened, nothing is charged against the daily profile budget. This is a browse. max_touches=N additionally opens up to N full profiles (profile AND posts together, in one pass), best-first, to CONFIRM the badge filters. Already-known people are served from cache for free and never counted against N. want_notes=true additionally drafts a connection note for the confirmed candidates, reusing profiles already read — no extra LinkedIn reads, ever. Nothing sends; drafts land in list_drafts. "#hiring" and "#opentowork" mean TWO DIFFERENT THINGS on LinkedIn, and which one the user means decides what the search costs: BADGE the frame on someone's PROFILE (is_hiring / is_open_to_work). It is NOT in any people-search result and NOT in their posts. Seeing it means opening that person's profile — one profile touch each — with a single exception: a full Recruiter seat can filter "open to work" at search time for free. This tool's `hiring` and `open_to_work` flags mean the BADGE. POST TEXT the hashtag someone typed into a POST. Free to search, opens nobody's profile, and says nothing about their badge. That is search_posts_by_topic, not this tool — "who POSTED about hiring" is a different question from "who HAS the hiring badge", and they return different people. Honesty contract, worth relaying to the user: `checked` is how many profiles this call actually opened, `cached` how many were reused free, `confirmed` how many really carry the badge, and `count - checked - cached` are candidates NOBODY has verified. When the daily budget is spent, the candidate list still comes back with `budget_exhausted` set — the tool never returns an empty list to mean "out of budget", and never silently stops early. Args: query: what to search for, e.g. "ML engineer" or "Head of Growth". location: plain-text location, e.g. "San Francisco" or "United States". limit: bucket size to search for (1-100; classic LinkedIn plans return at most 10). company / headline_keywords / exclude_headline_keywords / network_distance: free filters applied to the search results themselves — they cost nothing, so use them freely to cut the list before spending touches. Any-of within a filter, all-of across filters. network_distance: DISTANCE_1 (direct connections), DISTANCE_2, DISTANCE_3. hiring: set this to find people who really have the #hiring profile BADGE (not post text). It is the only way to get that answer: no LinkedIn plan can filter on the badge at search time, so candidates are ORDERED by the free signals that correlate with it and then CONFIRMED by opening profiles — 1 touch per candidate confirmed, on every tier, capped by max_touches. The response marks each confirmed candidate and counts them in `confirmed`. With max_touches=0 nothing is confirmed and this flag only changes the order. For "who POSTED about hiring" use search_posts_by_topic instead: free, and a different question with different people. open_to_work: set this to find people who really have the #opentowork profile BADGE (not post text). On a full Recruiter seat LinkedIn confirms it at search time for free (its own spotlight, 0 touches, results arrive pre-filtered); on every other plan — Recruiter Lite included — it falls back to order-then-confirm at 1 touch per candidate confirmed, capped by max_touches. The tool picks whichever route this account can actually use, and the response says which candidates are confirmed either way. posted_recently: neither badge nor post text — an ACTIVITY filter ("posted at all in the past 30 days", regardless of what about). Free at search time, Sales Navigator seats only; on other plans the search runs without it and `tier_note` says so. max_touches: how many profiles this call may open BEFORE answering (0-10, default 0). You wait for these. background_touches: how many of the best remaining candidates to confirm AFTER the answer is sent (0-10, default 0). You do NOT wait for these and they are NOT confirmed in this response — `background.queued` says how many are running. Ask again in a moment and they come back already confirmed, at no extra cost, because they land in the same cache. Use this to keep a long list moving without making the user wait: "here are 25 people, the best 8 are being confirmed now". want_notes: draft a connection note per confirmed candidate. Default false. ## Request body - FindProspectsRequest - `query` string, required - `location` string, required - `limit` integer - `company` string[], nullable - `headline_keywords` string[], nullable - `exclude_headline_keywords` string[], nullable - `network_distance` string[], nullable - `hiring` boolean - `open_to_work` boolean - `posted_recently` boolean - `max_touches` integer - `background_touches` integer - `want_notes` boolean ## Response `200` Successful Response - unknown ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/iridiumhqmcp/apis/iridium-linkedin-for-ai-agents.md) · [All operations](https://skmtc.dev/iridiumhqmcp/apis/iridium-linkedin-for-ai-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/iridiumhqmcp/apis/iridium-linkedin-for-ai-agents/revisions/b9f5e020543c?raw)