LogoLogo
  • Endorsed Platform Overview
  • API Overview
  • Data Import
  • Candidate Querying
  • Support
  • Common Workflows
    • Applicant Tracking Systems
      • Bring AI-powered candidate search to your users
      • Bring lookalike search to your users
      • Bring AI-powered evaluations to your users
    • Recruitment Marketplaces
      • Screen New Marketplace Applicants for Internal Team
      • Find, Score, and Summarize Talent for Client Jobs for Internal Team
      • Talent Search APIs for Your Users
  • Reference
    • API Reference
      • Access Tokens
      • Jobs
      • Spotlights
      • Job Criteria
      • Nomination Stages
      • Candidates
      • Nominations
      • Attachments
      • Rankings
      • Summaries
      • Tags
      • Candidate Tags
      • Job Tags
      • Criterion Evaluations
      • SDK (Coming Soon)
      • Quick Start (Coming Soon)
  • Resources
    • How to Write Good Evaluation Criteria
    • HIRE Accuracy Benchmark
      • HIRE Benchmark: Setting the Standard for Candidate Evaluation AI
Powered by GitBook

© 2024 Endorsed

On this page
  • Get Candidate rankings
  • Get Candidate ranking by Candidate ID
  1. Reference
  2. API Reference

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

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

q

string

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>

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

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.

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

{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}
{
  "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"
      }
    ]
  }
}

Last updated 1 year ago

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 for details.

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 for details.

Query Ranking Target
Query Ranking Target