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

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`)

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

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.

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.

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

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

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

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.

target_resource_id

string

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

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 4 months ago