Search people

Tool: search_people

The call returns named rows plus search_id and creates no people or lead group. Review the rows, then use continue_search with search_id, the returned search_version for another bounded turn only after the user explicitly asks for more. Never loop continuation turns automatically or broaden the filters while this search remains active without user agreement. Use save_search(search_id) once to create or append to a people group. For company-first sourcing, pass within_lead_group_id to freeze the eligible saved company roster, or pass all reviewed current_employer_domain values with per_company_limit in one call. The server advances as many company scopes as fit within the turn's request and execution-time budgets. Never issue one search_people call per company. When a saved company group grows, start a new search with the same within_lead_group_id and exclude the existing linked people group; the save recommendation appends approved rows back to that group. Skip known people with exclude_lead_group, exclude_sequence, exclude_crm, or exclude_profiles. exclude_crm is best-effort and capped; global eligibility is checked again before enrollment. A plain persona search defaults to people located in the US (location_country='United States') when you pass no location; set location or location_country to search elsewhere. NOT for: a known person's profile → get_person_profile; company discovery → search_companies.

Parameters

Returns named staged rows and a durable search_id; it does not create people or a lead group.

Company-first: pass a saved company group as within_lead_group_id, or pass every reviewed current_employer_domain with per_company_limit in one call. The search freezes its eligible roster and owns independent per-company progress. If the company group later grows, start a new search with the same within_lead_group_id plus exclude_lead_group=<existing people group>; the returned save recommendation appends approved rows to that same linked people group.

Every durable response returns search_version; pass that value to continue_search(search_id, search_version) for one bounded turn.

On the first save, use save_search(search_id, group_name=...) or save_search(search_id, lead_group_id=...) to commit approved rows.

Changing the persona, scope, or filters starts a new typed search.

Unknown named params are rejected with validation_error (a typo'd filter must never silently broaden the search) - unlike most operations, which ignore extras.

Sample request — success

{
  "title": "CEO",
  "limit": 25
}

Sample request — draft default

{
  "title": "CEO",
  "limit": 25
}

Sample request — named params

{
  "title": "CEO",
  "location": "United States",
  "limit": 25
}

Sample request — company scoped

{
  "within_lead_group_id": "software-companies-0013",
  "title": "CEO",
  "per_company_limit": 1,
  "limit": 1
}