search_candidates
Search for candidates by full-text query, skills, tags, sources, job pipeline, location, or resume status. Cursor-based pagination enables efficient browsing.
Instructions
Search candidates using Elasticsearch with rich filters and cursor-based pagination. Preferred over list_candidates when you need: full-text search (name, email, resume), filtering by skills, tags, sources, job pipeline, location, or resume presence. Pagination: pass cursor from the previous response meta.next_cursor to get the next page. IMPORTANT: if you change any filter or search parameter, omit cursor and start a new request — cursors are tied to a specific search context and will return wrong results if filters change.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Pagination cursor from the previous response meta.next_cursor. Omit this field entirely when changing any filter — cursors are bound to a specific search context. Cannot be combined with page. | |
| query | No | Full-text search across name, email, phone number, and resume text | |
| skill_ids | No | Comma-separated skill IDs — returns candidates who have ALL of these skills | |
| tag_ids | No | Comma-separated tag IDs — returns candidates who have ANY of these tags | |
| candidate_source_ids | No | Comma-separated source IDs — get IDs from list_sources | |
| job_ids | No | Comma-separated job IDs — returns candidates who have applied to these jobs | |
| has_resume | No | true = only candidates with a resume; false = only without | |
| country_id | No | Filter by country ID | |
| state_id | No | Filter by state/province ID | |
| city_id | No | Filter by city ID | |
| credited_to_user_ids | No | Comma-separated user IDs — returns candidates credited to these users | |
| current_company_ids | No | Comma-separated company IDs — returns candidates currently at these companies | |
| degree_ids | No | Comma-separated degree IDs — returns candidates with these degrees | |
| institute_ids | No | Comma-separated institute IDs — returns candidates from these institutions | |
| interviewer_ids | No | Comma-separated user IDs — returns candidates interviewed by these users | |
| page | No | Page number (default: 1). Cannot be combined with cursor. | |
| limit | No | Items per page (default: 20, max: 100) |