get https://api.recruitee.com/c//search/new/candidates
Calling this endpoint will return a collection of the company's candidates.
Limits
A call without parameters returns 60 candidates - just like the default pagination in Recruitee
Maximum number of candidates that can be returned with a single call is 10 000 - setting the limit parameter above the limit will return "Server internal error"
Note for Time filters
When applying filters involving time (e.g., created_at), ensure you use Unix Time format. For easy conversion, refer to the Unix Time Stamp website. This requirement applies to all fields in the column Possible values marked timestamp.
Candidates search accepts filters in a form of JSON array.
| Field | Type of filter | Possible values | Example |
|---|---|---|---|
| all | query | any string | {"field":"all","query":"Smith"} |
| average_score | gte (>=), gt (>), lte (<=), lt (<) | percentage values | {"field":"average_score","gte":76,"lte":100} |
| average_score | has_any, has_none, has_hidden | TRUE | {"field":"average_score","has_none":true} {"field":"average_score","has_any":true} |
| created_at (UI: Date created) | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"field":"created_at","gte":1548975600,"lte":1549061999} |
| emails_received_from_admins_ids (UI: Candidate received emails from...) | has_any, has_none | TRUE | {"field":"emails_received_from_admins_ids","has_any":true} |
| emails_received_from_admins_ids (UI: Candidate received emails from...) | has_one_of, has_all_of, has_none_of | array of IDs | {"field":"emails_received_from_admins_ids","has_one_of":[4256]} |
| emails_sent_to_admins_ids (UI: Candidate sent emails to...) | has_any, has_none | TRUE | {"field":"emails_sent_to_admins_ids","has_any":true} |
| emails_sent_to_admins_ids (UI: Candidate sent emails to...) | has_one_of, has_all_of, has_none_of | array of IDs | {"field":"emails_sent_to_admins_ids","has_one_of":[4191]} |
| gdpr_expires_at (UI: Retention period ends within...) | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"field":"gdpr_expires_at","gte":1548975600,"lte":1549061999} |
| gdpr_uncompleted_change_request_created_at (UI: Correction requests) | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"field":"gdpr_uncompleted_change_request_created_at","gte":0} |
| gdpr_uncompleted_removal_request_created_at (UI: Removal requests) | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"field":"gdpr_uncompleted_removal_request_created_at","gte":0} |
| has_cover_letter (UI: Cover letter) | eq | true, false | {"field":"has_cover_letter","eq":true} |
| has_cv (UI: CV or resume) | eq | true, false | {"field":"has_cv","eq":true} |
| has_email (UI: Email address) | eq | true, false | {"field":"has_email","eq":true} |
| interviewers_ids (UI: Evaluated by) | has_any | TRUE | {"field":"interviewers_ids","has_any":true} |
| interviewers_ids (UI: Not evaluated by) | has_none | TRUE | {"field":"interviewers_ids","has_none":true} |
| interviewers_ids (UI: Evaluated by) | has_one_of, has_all_of | array of IDs | {"field":"interviewers_ids","has_one_of":[4256]} |
| job_fit_score (UI: Job fit score) | gte (>=), gt (>), lte (<=), lt (<) | percentage values | {"field":"job_fit_score","gte":76,"lte":100} |
| job_fit_score (UI: Job fit score) | has_any, has_none, has_hidden | TRUE | {"field":"job_fit_score","has_none":true} {"field":"job_fit_score","has_any":true} |
| last_activity_at | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"field":"last_activity_at","gte":1548975600,"lte":1549061999} |
| positive_ratings (UI: Evaluations) | gte (>=), gt (>), lte (<=), lt (<) | percentage values | {"field":"positive_ratings","gte":76,"lte":100} |
| positive_ratings (UI: Evaluations) | has_any, has_none | TRUE | {"field":"positive_ratings","has_none":true} {"field":"positive_ratings","has_any":true} |
| source (UI: Candidate origin) | in, not_in | array of strings; ["career_site","email","manual","import"] | {"field":"source","in":["career_site"]} |
| status (UI: Candidate Status) | in | array of strings; ["Qualified", "Disqualified", "New"] | {"field":"status","in":["qualified"]} |
| updated_at | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"field":"updated_at","gte":1548975600,"lte":1549061999} |
| address | has_any, has_none | TRUE | {"filter":"address", "has_any":true} |
| address, text (UI: Address contains/does not contain) | contains, not_contains | array of strings | {"filter":"address", "text": {"contains":["street"]}} |
| admin, id (UI: Added by) | has_any | TRUE | {"filter":"admin","id":{"has_any":true}} |
| admin, id (UI: Added by) | in, not_in | array of IDs | {"filter":"admin", "id":{"not_in":[123]}} |
| boolean_* (candidate "*yes/no field title") | has_any, has_none | TRUE | {"filter":"boolean_is_available", "has_any":true} |
| boolean_* (candidate "*yes/no field title"), flag | eq | true, false | {"filter":"boolean_is_available", "flag":{"eq":true}} |
| date_of_birth | has_any, has_none | TRUE | {"filter":"date_of_birth", "has_any":true} |
| date_of_birth, date | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"filter":"date_of_birth", "date":{"lte":946684800}} |
| disqualifies, kind | in, not_in | array of strings ("admin", "system") | {"filter":"disqualifies", "kind":{"in":["admin"]}} |
| disqualifies, reason | has_any, has_none | TRUE | {"filter":"disqualifies", "reason":{"has_any":true}} |
| disqualifies, reason | in, not_in, all_in | array of strings | {"filter":"disqualifies", "reason":{"in":["Not a fit"]}} |
| dropdown_* (candidate "*dropdown field title") | has_any, has_none | TRUE | {"filter":"dropdown_mentor", "has_any":true} |
| dropdown_* (candidate "*dropdown field title"), value | in, not_in | array of strings | {"filter":"dropdown_mentor", "value":{"in":["John"]}} |
| education | has_any, has_none | TRUE | {"filter":"education", "has_any":true} |
| education, degree (UI: Degree contains/does not contain) | contains, not_contains | array of strings | {"filter":"education", "degree":{"contains":["major"]}} |
| education, description | contains, not_contains | array of strings | {"filter":"education", "description":{"contains":["programming"]}} |
| education, start_date | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"filter":"education", "start_date":{"gte": 946684800}} |
| education, end_date | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"filter":"education", "end_date":{"gte": 946684800}} |
| education, major | contains, not_contains | array of strings | {"filter":"education", "major":{"contains":["biology"]}} |
| education, school | contains, not_contains | array of strings | {"filter":"education", "school":{"contains":["university"]}} |
| eeo_status, template_name | in | array of strings | {"filter":"eeo_status", "template_name":{"in":["x"]}} |
| eeo_data_status | in | {"filter":"eeo_data_status","in":["completed"]} | |
| events | has_any, has_none | TRUE | {"filter":"events", "has_any":true} |
| events, kind | in, not_in | array of strings; ["meeting","onsite","video", "call"] | {"filter":"events", "kind":{"in":["meeting"]}} |
| events, starts_at | gte (>=), gt (>), lte (<=), lt (<), not_gte, not_gt, not_lte, not_lt | timestamp (string / number) | {"filter":"events", "starts_at":{"gte": 1549061999}} |
| experience | has_any, has_none | TRUE | {"filter":"experience", "has_any":true} |
| experience, company | contains, not_contains | array of strings | {"filter":"experience", "company":{"contains":["Tellent"]}} |
| experience, description | contains, not_contains | array of strings | {"filter":"experience", "description":{"contains":["programming"]}} |
| experience, start_date | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"filter":"experience", "start_date":{"gte": 1549061999}} |
| experience, end_date | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"filter":"experience", "end_date":{"gte": 1549061999}} |
| experience, location | contains, not_contains | array of strings | {"filter":"experience", "location":{"contains":["London"]}} |
| experience, title | contains, not_contains | array of strings | {"filter":"experience", "title":{"contains":["manager"]}} |
| followers, id | has_any, has_none | TRUE | {"field":"followers","has_any":true} |
| followers, id | in, not_in, all_in | array of IDs | {"filter":"followers","id":{"not_in":[123]}} |
| gender | has_any, has_none | TRUE | {"filter":"gender", "has_any":true} |
| gender, value | in, not_in | array of strings | {"filter":"gender", "value":{"in":["female"]}} |
| hiring, hired_at | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"filter":"hiring", "hired_at":{"gte":946684800}} |
| hiring, job_starts_at | gte (>=), gt (>), lte (<=), lt (<) | timestamp (string / number) | {"filter":"hiring", "job_starts_at":{"gte":946684800}} |
| hiring, status | in | array of strings | {"filter":"hiring", "status":{"in":["active"]}} |
| interviewers, id | in, not_in | array of IDs (int) | {"filter":"interviewers","id":{"not_in":[4256]}} |
| jobs | has_any, has_none | TRUE | {"filter":"jobs", "has_any":true} |
| jobs, city | in, not_in | array of strings | {"filter":"jobs", "city":{"in":["Chicago"]}} |
| jobs, country_code | in, not_in | array of strings | {"filter":"jobs", "country_code":{"in":["US"]}} |
| jobs, department_id | has_any, has_none | TRUE | {"filter":"jobs", "department_id":{"has_any":true}} |
| jobs, department_id | in, not_in | array of numbers / strings | {"filter":"jobs", "department_id":{"in":[1758224]}} |
| jobs, id | has_any, has_none, has_any_followed, has_none_followed | TRUE | {"filter":"jobs", "id":{"has_any":true}} |
| jobs, id | in, not_in, all_in | array of IDs (int) | {"filter":"jobs", "id":{"in":[1]}} |
| jobs, locations.id | has_any, has_none | TRUE | {"filter":"jobs", "locations.id":{"has_any":true}} |
| jobs, locations.id | in, not_in | array of IDs (int) | {"filter":"jobs", "locations.id":{"in":[2]}} |
| jobs, state_code | in, not_in | array of strings | {"filter":"jobs", "state_code":{"in":["AZ"]}} |
| jobs, status | in, not_in | array of strings | {"filter":"jobs", "status":{"in":["applied"]}} |
| language_skill | has_any, has_none | TRUE | {"filter":"language_skill", "has_any":true} |
| language_skill, language_code | in, not_in, has_all_of | array of strings | {"filter":"language_skill", "language_code":{"in":["en"]}} |
| locations, id | in, not_in | array of IDs (int) | {"filter":"locations", "id":{"in":[1]}} |
| multi_line_* (candidate "*multi-line field title") | has_any, has_none | TRUE | {"filter":"multi_line_interests", "has_any":true} |
| multi_line_* (candidate "*multi-line field title"), text | contains, not_contains | array of strings | {"filter":"multi_line_interests", "text":{"contains":["swimming"]}} |
| nationality | has_any, has_none | TRUE | {"filter":"nationality", "has_any":true} |
| nationality, country_code | in, not_in | array of strings | {"filter":"nationality", "country_code":{"in":["US"]}} |
| potential_duplicate | eq | true, false | {"filter":"potential_duplicate", "eq":true} |
| questionnaire_answers | has_any, has_none | TRUE | {"filter":"questionnaire_answers", "has_any":true} |
| questionnaire_answers, question_title | in, not_in | array of strings | {"filter":"questionnaire_answers", "question_title":{"in":["Describe your experience"]}} |
| questionnaires_filled | has_any, has_none | TRUE | {"filter":"questionnaires_filled", "has_any":true} |
| questionnaires_filled, template_name | in, not_in | array of strings | {"filter":"questionnaires_filled", "template_name":{"in":["Initial questionnaire"]}} |
| questionnaires_received | has_any, has_none | TRUE | {"filter":"questionnaires_received", "has_any":true} |
| questionnaires_received, template_name | in, not_in | array of strings | {"filter":"questionnaires_received", "template_name":{"in":["Initial questionnaire"]}} |
| single_line_* (candidate "*single-line field title") | has_any, has_none | TRUE | {"filter":"single_line_region", "has_any":true} |
| single_line_* (candidate "*single-line field title"), text | contains, not_contains | array of strings | {"filter":"single_line_region", "text":{"contains":["Europe"]}} |
| skills | has_any, has_none | TRUE | {"filter":"skills", "has_any":true} |
| skills, text | in, not_in, contains, not_contains, has_all_of | array of strings | {"filter":"skills", "text":{"in":["programming"]}} |
| sources, id | has_any, has_none | TRUE | {"filter":"sources", "id":{"has_any":true}} |
| sources, id | in, not_in, all_in | array of IDs (int) | {"filter":"sources", "id":{"in":[1]}} |
| stages, name | has_any, has_none | TRUE | {"filter":"stages", "name":{"has_any":true}} |
| stages, name | in, not_in | array of strings | {"filter":"stages", "name":{"in":"Phone interview"}} |
| tags, id (UI: Has tag) | has_any, has_none | TRUE | {"filter":"tags", "id":{"has_any":true}} |
| tags, id (UI: Has tag) | in, not_in, all_in | array of IDs (int) | {"filter":"tags", "id":{"in":[1]}} |
| talent_pools, id | has_any, has_none, has_any_followed, has_none_followed | TRUE | {"filter":"talent_pools", "id":{"has_any":true}} |
| talent_pools, id | in, not_in, all_in | array of IDs (int) | {"filter":"talent_pools", "id":{"in":[1]}} |
| tasks | has_any, has_none | TRUE | {"filter":"tasks", "has_any":true} |
Additional notes
"all" searches the following fields of candidates:
- candidate name,
- email addresses
- phone numbers
- tags
- sources
- candidate offer assignments - returns candidates with assignments to offers fitting the query
- current stage name
- cover letter
- cv content