Required permissions: research:trigger.

Given a company — any company, by its website (or LinkedIn page or name), or an account in your workspace — and a stakeholder definition, return the people at it who fit, best first, each with a reason. Synchronous and read-only: the answer comes back in one response, typically in 5–20 seconds (the server gives up at 25 with 503 stakeholder_search_failed, so set your client timeout above that and retry once on retry_later), and nothing is written to your workspace. Import the ones you want with POST /v1/people/batch.

Company identity. Trayo identifies the company from its LinkedIn page first, then its website, then its name. The response includes people who fit your definition and explains each result in whyThisPerson. company.resolvedBy says which identity was used. Before importing anyone, make sure that company.name and company.website identify the intended company. A guessed handle or a common name can identify a different company.

Public REST and MCP usage is recorded without daily usage caps, workspace quota cutoffs or lookup quotas for now. Workspace request pacing still applies. The definition. Send one per call, in plain prose — the roles that own or buy what you sell, the roles that influence, the roles to skip. Omit it to use the workspace's own definition; if that is unset too, a search for senior roles applies and definition.source says default so you know the result is senior people of any function rather than your buying committee. A definition sent here changes nothing on the workspace.

Read candidates with people. candidates: 0 means Trayo found no people with the requested keywords at this company. candidates > 0 with people: [] means the selection judged none of them to fit — a real answer, not an error. Fewer than limit come back when fewer fit.

Near-misses. When nobody fits, nearMisses holds up to 3 of the closest candidates, each with belowThreshold: true and a reason saying what their role lacks, and next names their titles. They did not fit: offer them as alternatives rather than importing them as the buying committee.

Personas. Each person carries matchedPersona, and coverage lists every persona with whether anyone in people matched it — so a persona with no match (no champion, say) is stated, not guessed from titles, and next says what to do about it. The names come from personas in the request, or from the workspace's saved personas when its definition applies. Each label is checked after selection against the job's function and seniority (a saved persona's seniority and rationale are read too) and replaced or cleared when it does not hold; the person stays. One person can cover several personas: a CTO also covers "VP Eng".

Repeatable. Repeating a search within a week normally returns the same people.

Many companies. For up to 50 companies at once, use POST /v1/stakeholders/search/batch rather than one call per company.

Compared with POST /v1/find. Find's contacts lane searches the web and identifies people from any source; this searches Trayo's data for people who fit your definition. Use find when the company is not in our data (company_not_found) or when you want breadth over fit.