Search candidates
searchCandidatesSearch Clera's vetted candidates who are open to opportunities and recently active or actively looking. Returns profiles with name, photo and LinkedIn, never email or phone: requestIntro is how your company meets a candidate, and the returned id is what it takes. Best results: write the ideal candidate in profile (four fields in Clera's stored profile style) and bind the role with jobId; then candidates are ranked by profile similarity, keyword match and the role's past requests and passes, and each carries fit flags against the role (salary, visa, location, workplace, experience, prior decline). Candidates with a confirmed location or visa conflict against the role are excluded from results (your own contradicting filter overrides that dimension, and missing data never excludes); the other flags are advisory and never block anything. Without profile: newest profiles first, or text relevance when search_term is set. Cannot look a person up by name: names, emails and LinkedIn URLs are not searchable, so searching one returns nothing even when that person is on Clera. Asked about a named person, say name lookup is not possible, then offer listRecommendedCandidates, listPendingIntroRequests, or a search by role and skills. Never returned: candidates already shown to your company, your own employees, or people who work at Clera; a zero result does not prove the person is not on Clera. Until the company has written in its Clera Slack channel, each call, including each page, costs one of 10 searches per day, so set the filters you need before searching rather than running broad passes. Re-fetching your picks with filters.talent_ids alone is free.
Clera privately records this tool's inputs and results for usage tracking and support.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"filters": "<filters>"
},
"name": "searchCandidates"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1). | |
| jobId | No | The open role this search is for, resolved by name from the job tool's list command whenever the user names or implies a role; never ask for an id and never present a role picker on search. Adds seed ranking from the role's past requests and passes, the role's rubric in the result and fit flags on every candidate. Omit for a clean-slate search: the result then says 'no role: no seeds, no rubric, no fit flags'. Pass it again on filters.talent_ids re-fetches or the flags are gone. | |
| orgId | No | Organization to act as. Only needed when you belong to more than one organization. | |
| filters | Yes | Search filters. All array filters are exact-value matches: get valid values for role_names, skills, job_types, preferred_work and countries from listFilterOptions, and resolve work_history / education_history / boolean_tags values with suggestFilterValues. Start focused and adjust based on the returned counts. A filter that contradicts the bound role (a country the role is not in) still wins; the result states the override. | |
| profile | No | The ideal candidate written in Clera's stored talent-profile style: each field is embedded and compared against that same field on every candidate profile, so match the format, not natural-language prose. At least one field. With jobId, a missing field falls back to the role's own profile text; without jobId it drops out of the ranking. Returns one ranked page of up to per_page candidates (no page 2); search_term stays keywords only. | |
| per_page | No | Results to return. Up to 10 for browsing; the card view shows them all. Up to 50 for a wide scan when you screen candidates yourself against a brief or job description: profiles come back as one dense text line each (oneliner, location, experience, employers, school, three highlight bullets) with no cards and no JSON block, roughly 0.5 KB per profile, so 50 profiles is about 25 KB or 6k tokens. If your client caps tool results below that, you might save the result to a file and screen from there. Put must-have tech in the skills or boolean_tags filters; wide-scan lines carry highlights rather than the full skill list. Then call again with filters.talent_ids set to your picks to display them as cards, each with your fit reasoning underneath. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | ||
| orgId | Yes | ||
| counts | No | ||
| talents | Yes | ||
| semantic | No | ||
| conflicts | No | ||
| openRoles | Yes | The company's open roles, for picking which role an intro request targets. | |
| pagination | Yes | ||
| filterParams | Yes |