Find Person
Find ONE specific person by name — optionally pinned by where they used to work — and get
a definitive answer in a single call. The user never needs their LinkedIn id or URL.
CHOOSING BETWEEN discover_prospects AND find_person
The deciding question: does the user NAME a specific person, or DESCRIBE a kind of person?
USE find_person when the user names someone (a first and last name), however much else
they say about them:
- "Message Jane Doe, she used to be at Acme."
- "Is this the John Smith who was at Acme?"
- "Find Pat Lee at Globex and connect."
Returns who they are plus proof (e.g. Acme, 2018-2024). Cost: 1 search plus up to 2
profile reads. Drafts nothing. To write to them afterwards, pass the handle to
schedule_dm_to_person.
USE discover_prospects when the user describes a GROUP by role, place or topic and wants
connection notes written for whoever is found:
- "Find 5 ML engineers in San Francisco and draft notes to them."
- "Reach out to heads of growth in Austin."
Searches by query and location, reads each person's profile AND posts, and drafts a note
per person. Cost: 1 search plus 2 reads per person (about 11 actions for 5 people).
Nothing sends; drafts land in list_drafts. Use it only when the user wants drafts.
NEITHER (use find_prospects or search_prospects) when the user wants a list to browse, or
to check a badge such as #hiring, with no notes wanted.
NEVER use discover_prospects to look up a named person: it cannot filter by name or former
employer, it returns strangers, and it spends about 11 actions doing so. NEVER use
find_person to build a list: it returns at most 2 people.
AMBIGUOUS: "Find me Acme alumni named Jane."
This could mean one specific Jane (find_person) or any number of Janes who used to work
at Acme, with notes drafted (discover_prospects). A first name only, or a plural, is a
group. DO NOT GUESS: the two cost very different amounts and discover_prospects drafts
messages. Ask the user one question before calling either, for example:
"Do you mean one specific person (give me their full name), or should I find several
people matching this and draft notes to them?"
Then call exactly one tool.
If the user gave a full name plus any context, choose find_person without asking. Ask
only when the request could fit both.
LinkedIn applies the name and employer filters itself, so a match already satisfied them.
The profile is then read (profile only, no posts; at most 2 matches; cached) to show WHEN:
`proof` lists the matching job, e.g. Acme, Software Engineer, 2018-2024, status "past".
Read `verdict`:
confirmed exactly one person matched every filter you gave. Use its `handle`.
ambiguous two or more did. Compare `headline` and `location`, or add a filter
(company, location, title) and call again.
unverified NOBODY matched your filters; these people share only the name. Do not
present them as the person asked for.
none nobody by that name.
A match is a person who satisfies the filters, not proof they are the one the user means:
check `headline` and `location` against what the user said.
Cost: 1 search, plus 1 profile read per match when `evidence` is on (free if cached).
`evidence=false` skips the profile read: the match is still confirmed, with no dates.
If the daily budget is spent the matches still come back, without `proof`, and
`budget_exhausted` is set.
SEVERAL PEOPLE: send `people` (a list of the same fields, up to 50) instead of `name`. Up to 3
are answered right here as {"status": "done", "results": [...]}. More than 3 return a job_id
at once, keep working in the background at a pace LinkedIn tolerates, and email the user when
they pause or finish. Read them with get_job: results appear as they come in, and each
confirmed person carries a handle you can use straight away.
Args:
name: full name, e.g. "Jane Doe". The last word is the surname. (Or send `people`.)
past_company: a company they USED to work at, e.g. "Acme".
company: a company they work at NOW.
location: where they are now, e.g. "San Francisco".
title: words from their current title, e.g. "Chief Scientist".
keywords: a soft hint (e.g. a former city). Narrows the search; proves nothing.
evidence: read the profile to show dates (default true).
include_history: also return their whole work history (default false).
Returns {"verdict", "matches", "more", "searches", "profiles_opened", "budget_exhausted",
"note"}. Each match: handle, name, headline, location, distance, profile_url, and (when
read) proof [{company, role, from, to, status}]. Pass `handle` straight to
schedule_dm_to_person, get_linkedin_profile (for posts) or enroll_prospect.
### Responses:
**200**: Successful Response (Success Response)
Content-Type: application/json