Candidate Querying

The Endorsed Platform supports advanced search & querying of Candidates with the following features. All search & querying functions are facilitated by the GET /candidate_rankings API endpoint.

  1. Job Match

  2. Natural Language Search

  3. Lookalike Search

In order to use these functions, you must have already provided Jobs, Nomination Stages, Candidates, Nominations, and Attachments via our Import APIs. Visit that first if you haven't already done so:

Data Import

Ranking Queries

You can search for Candidates for a specific Job, or you can search for Candidates across all Jobs in your organization.

All ranking query functions support both searching against the Candidates within a Job by setting the filter_job_id query parameter, or against your entire set of all Candidates by not setting the filter_job_id query parameter. This allows standard use cases for searching all candidates who have actively applied for a job OR complex use cases for searching an entire candidate dataset for a relevant candidate.

Each of the types of queries are useful for searching against a pool of Candidates for rankings based upon:

QueryUse Case

Job Match

Relevance to a given job and details regarding that job (i.e. job description, etc.)

Natural Language Search

Relevance to a flexible input semantic search query.

Example: Experienced in designing mobile applications and proficient in Figma

Attachment Match

"Lookalike search". Relevance to a target candidate who has applied or an input attachment representing a theoretical or ideal candidate. Example: target_resource_id: urn:**

For each of the above query options, please see the API Reference for more details on request, response, and expected errors.

Result Handling


In order to decorate the necessary data to return or render in your UI, you can decorate the id fields we return in the above ranking endpoints against our REST APIs.

FieldDecoration Step


Call GET /candidates using the list of UUIDS to decorate the Candidate entities [See API Reference]


Call GET /summaries using the list of UUIDS to decorate the Summary entities [See API Reference]

Coming soon: GraphQL API so you can request the decorated response in a single query. Please contact, and our team will happily discuss requirements and timelines.


Our Querying endpoints support pagination.

Parameter: offset: number Used to specify the starting index to return, starting at 0.

Parameter: limit: number Specify the maximum number of results to return.

For example, if a result set has 100 Applicants to return and you only want to retrieve and display the third page of 10, you would use ...&offset=20&limit=10.

Last updated

© 2024 Endorsed