A Candidate Ranking that represents how relevant a Candidate is to a certain set of query criteria.
Relationships:
Ranking to Candidate is 1-1
Ranking to Summary is 1-1
Query Ranking Target
You can search rank against different types of resources: Job, Candidate, Attachment, and string.
What's the difference between target_resource_id and filter_job_id? The target_resource_id determines how the candidates results are ranked (aka the relevance order) and does NOT control filtering - all results will be returned if all results are paginated through. The filter_job_id controls whether specific results are returned at all but does NOT control relevance. Filtering may be useful for example for filtering on candidates who have actively applied to a job.
Below are each of the ranking targets for the query and their corresponding use cases:
Examples
Using target_resource_id
curl -X GET "${BASE_URL}/api/v1/candidate_rankings?target_resource_id=e69e1198-f02e-4340-ab24-51901afcefac&filter_job_id=e5e597e2-cdac-4339-a1aa-74dcd3895fc3&offset=100&limit=50" \
-H"Authorization: Bearer ${ACCESS_TOKEN}"
Using q
curl -X GET "${BASE_URL}/api/v1/candidate_rankings?q=Experienced%20with%20Figma&filter_job_id=e5e597e2-cdac-4339-a1aa-74dcd3895fc3&offset=100&limit=50" \
-H"Authorization: Bearer ${ACCESS_TOKEN}"
There are two endpoints for retrieving rankings, one to retrieve a full list of rankings and one to retrieve the score evaluation for just a single candidate.
{"is_error":true,"error": {"code":"UNAUTHENTICATED","issues": [ {"message":"Resource requires authentication. Please provide a valid access token." } ] }}
{"is_error":true,"error": {"code":"INTERNAL_SERVER_ERROR","issues": [ { "message": "An unexpected error occurred on our end. Please try again later, and if the problem persists, contact our support team"
} ] }}
{
"is_error": true,
"error": {
"code": "NOT_FOUND",
"issues": [
{
"message": "No summary found for candidate aaa45510-ff8a-48d1-b89b-2fb266ecff4c and job b70ecb75-fdb2-4737-a68a-5308d7844ecd"
}
]
}
}
{
"is_error": true,
"error": {
"code": "INTERNAL_SERVER_ERROR",
"issues": [
{
"message": "An unexpected error occurred on our end. Please try again later, and if the problem persists, contact our support team"
}
]
}
}
Ranking results by relevance to a Job (e.g., job description, title)
Candidate Match
target_resource_id
A /candidates entity id
Ranking results by relevance to an existing Candidate
Attachment Match
target_resource_id
A /attachments entity id
Ranking results by relevance to a theoretical or ideal candidate based upon an Attachment (e.g., resume)
Semantic Search / Natural Language Search
q
A string query
Ranking results by relevance to an input semantic query (e.g., Experienced in Microsoft Excel)
target_resource_id
string
A UUID id of an entity from either of the entity resources: /jobs,/attachments , OR /candidates. This target entity is used to search other Candidates that are similar or relevant to that entity. Only one parameter, either target_resource_id or q, must be specified. Must See Query Ranking Target for details.
q
string
A query string to semantically search Candidates against. Ex: Experienced in designing mobile applications and proficient in Figma. Only one parameter, either target_resource_id or q, must be specified. See Query Ranking Target for details.
filter_job_id
string
The Job UUID from the /jobs entity resource to filter only Candidates which were applied to the job. If not provided, will query against all Candidates under your organization.
offset
integer
Starting offset index of the first result for pagination. Default: 0
limit
integer
Pagination result limit. For example, if offset = 100, limit = 100, the returned results will be in the range of 100-199 inclusive. Default: 100. Max: 100
score_version
integer
The ranking algorithm Endorsed uses to order results and compute score. Version 1 uses vector similarity between the Candidates' relevant Attachments and the Job description. Version 2 uses the ratio of matching Criterion Evaluations.
Each version will compute score differently, so by setting the version explicitly, you can ensure returned scores are all from the same algorithm and you don't mix different types of scores in your application.
Must be either 1 or 2. Default: 1.
Authorization*
string
Authorization header containing the Bearer Access Token from the /auth/tokens endpoint. Example: Bearer <ACCESS_TOKEN>
target_resource_id
string
A UUID id of an entity from either of the entity resources: /jobs,/attachments , OR /candidates. This target entity is used to search other Candidates that are similar or relevant to that entity.
filter_job_id
string
The Job UUID from the /jobs entity resource to filter only Candidates which were applied to the job. Required at this time.
score_version
integer
The ranking algorithm Endorsed uses to order results and compute score. Version 1 uses vector similarity between the Candidates' relevant Attachments and the Job description. Version 2 uses the ratio of matching Criterion Evaluations.
Only Version 2 is supported by this endpoint. Default is 2.