Rankings

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:

Use Case Type	Query Parameter	Value Type	Description
Job Match	target_resource_id	A /jobs entity id	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)

Examples

cURL

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.

Get Candidate rankings

GET https://endorsed.ai/api/v1/candidate_rankings

Query Parameters

Name	Type	Description
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.

Headers

Name	Type	Description
Authorization*	string	Authorization header containing the Bearer Access Token from the /auth/tokens endpoint. Example: Bearer <ACCESS_TOKEN>

200 Successful

{
  "is_error": false,
  "results": [
    {
      "score": 0.74,
      "candidate_id": "aaaad869-f919-472e-8142-29e5265d546f",
      "candidate_remote_id": "WVJ1n-mWVFcbkAPxkDrrA",
      "summary_id": "bbbb6d91-871c-453b-81bf-370bce9921a3",
      "nomination_id": "6702ef79-8d46-4143-92a2-83275b9ad51b"
    },
    {
      "score": 0.7325,
      "candidate_id": "cccc89de-c44d-4164-924a-569c2992dde3",
      "candidate_remote_id": "n3O_eaU4pzMM6Iow2QkaR",
      "summary_id": "dddd38ea-774e-43df-bf1f-1c8e0474542e",
      "nomination_id": "6702ef79-8d46-4143-92a2-83275b9ad51b"
    },
    {
      "score": 0.57,
      "candidate_id": "eeeebc51-babe-4668-84d0-94f22d58d4b8",
      "candidate_remote_id": "44Z84EvHejLxJl8OaxdOh",
      "summary_id": "ffffb070-4d79-4847-9077-fbe7e8860d72",
      "nomination_id": "6702ef79-8d46-4143-92a2-83275b9ad51b"
    }
  ]
}

401 Unauthorized

{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}

500: Internal Server Error

{
  "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"
      }
    ]
  }
}

Get Candidate ranking by Candidate ID

GET https://endorsed.ai/api/v1/candidate_rankings/{candidate_id}

Retrieve a single Candidate Ranking result, including evaluated score for a given Candidate.

Query Parameters

Name	Type	Description
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.

200 Success

{
  "is_error": false,
  "result": {
     "score": 0.74,
     "candidate_id": "aaaad869-f919-472e-8142-29e5265d546f",
     "candidate_remote_id": "WVJ1n-mWVFcbkAPxkDrrA",
     "summary_id": "bbbb6d91-871c-453b-81bf-370bce9921a3",
     "nomination_id": "6702ef79-8d46-4143-92a2-83275b9ad51b"
  }
}

202 In Progress

{
  "is_error": false,
  "result": {
     "score": null,
     "candidate_id": "aaaad869-f919-472e-8142-29e5265d546f",
     "candidate_remote_id": "WVJ1n-mWVFcbkAPxkDrrA",
     "summary_id": null,
     "nomination_id": "6702ef79-8d46-4143-92a2-83275b9ad51b"
  }
}

401 Unauthorized

{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}

404 Not Found

{
  "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"
      }
    ]
  }
}

500 Internal Server Error

{
  "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"
      }
    ]
  }
}