Skip to main content

Searching candidates via Candidate API


The Candidate API allows you to retrieve a list of candidates based on keyword search. This search operates in a similar fashion to a manual search done in our interface.

In order to search for a candidate using the API, search keywords will have to be entered in the parameter.

Standard search

When you're searching for candidates, SmartRecruiters will treat each keyword as an individual phrase. This is called tokenization or stemming of the search input. In this process, separators between words such as spaces, or punctuation marks, are used to identify individual keywords. The separators are removed from the search, and each keyword is then searched by individually. For example, this query:

product manager 

 will return candidates with profiles that contain "product" or "manager". To avoid tokenization of search input, use double quotes to search for an entire set of words. For example:

"product manager"

will return candidates with profiles that contain the phrase "product manager", but not "product" or "manager" alone. Including your search keywords between double quotes ensures the system will look for the whole text.

Additionally, when performing a keyword search, our system reduces entered keywords to their stem words by removing suffixes. For example, if you search for "build", "builder" or "building", the stem word "build" will be used in the search, and yield appropriate results. This also means the search won't be one hundred percent precise but will have a degree of fuzziness.

When looking for a candidate's email address, the @ symbol is also considered as a separator. If the email is entered as a single search parameter, the system will look for separate search terms located before and after the @. To search for the entire email address, please always include it between double quotes


  • Searching for "" would return an indexed search with "john", "mail" and "com" as the search parameters
  • Search for "" would return an indexed search with "" as the single search parameter

Boolean queries for candidates

You can also use Boolean operators when searching for candidates. SmartRecruiters evaluates Boolean queries with the same relevance calculation as any regular keyword search. The operators determine which candidates are included or excluded from the results.

AND  Find all candidate profiles that have all keywords joined by this operator. Useful for narrowing down your search with additional keywords.
OR Find candidates profiles with one or more keywords joined by this operator. Useful when there are common synonyms for a skill or job title that might appear on a candidate's profile.
NOT Use this operator to exclude all candidates who have an unwanted keyword in their profile.

Use parentheses ( ) to combine operators and create boolean strings. Enclose multi-word phrases in " " so that SmartRecruiters looks for the whole phrase, not the individual words.

Here's an example of all four in action:

(“Sales” OR “Account Manager”) AND (“CRM” AND “marketing”) NOT (“B2B”)

Always remember to encase your search terms in double-quotes if they are composed of more than one word, but not the logical operators, otherwise, they will be treated as part of a larger search term.

Special character encoding

You can also submit your queries with special characters being percent-encoded. Some characters you may find useful to encode:

Space " % - . \ _ @ ! # $ ? : , +
%20 %22 %25 %2D %2E %5C %5F %40 %21 %23 %24 %3F %3A %2C %2B

This means that queries are valid whether they are submitted with explicit characters, or with percent-encoded characters. For example:

curl -X GET '""&limit=10' -H "accept: application/json" -H "X-SmartToken: ..."


curl -X GET '' -H "accept: application/json" -H "X-SmartToken: ..."

 will yield the same results. We usually recommend submitting special characters such as "+" as percent-encoded, to ensure maximum compatibility.


When you search for candidates in SmartRecruiters, we look at a number of different fields and give these fields different weights. Here are all the fields we search on, in order of weight:  

  1. First Name
  2. Last Name
  3. Email
  4. City
  5. State
  6. Current Position at current company
  7. Tags
  8. Skills - parsed from resume.
  9. Past Positions at past companies
  10. Education
  11. Job Applied To
  12. Attached Resume

Weighting determines the relevance of the results returned by SmartRecruiters. SmartRecruiters determines the relevance by counting the number of instances of the keyword and examining the location (field) of each instance. 

For example, a candidate with keyword Marketing in their “Current Position” will be ranked higher compared to a candidate with two instances of "Marketing" in their “Skills”, because Skills have a lower weight than "Current Position."