Custom Candidate Search and Ranking API | SupportFinity Help Center

Introduction

The Custom Candidate Search and Ranking API helps you evaluate multiple candidates against any set of custom search criteria that you define.

You submit:

An array of candidate CVs
A set of custom criteria, each describing what you are looking for

The API returns, for each candidate:

A rank among all candidates
A yes / no for every criterion
A total score
A confidence level
An explanation for each criterion on why it is considered present or not

This allows you to build very flexible search and screening flows, tailored to your hiring needs.

1. Endpoint Information

Endpoint:
POST /ai/custom-criteria-ranking

Description:
Evaluates a list of candidates against a set of custom criteria and returns per candidate ranking, yes / no per criterion, total score, confidence level, and explanations.

Version: 1.0

2. Authentication

Required: Yes
Type: Bearer Token

Header:

Authorization: Bearer <token>

3. Request

HTTP Method

POST

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be `application/json`

Request Body

Content-Type: application/json

Schema

Field	Type	Required	Description
candidates	array of CandidateDTO	Yes	List of candidates to evaluate
criteria	array of CriterionDTO	Yes	Custom criteria defined by the user

CandidateDTO

Field	Type	Required	Description
id	string	Yes	Unique candidate identifier
name	string	No	Candidate display name
candidateCV	string	Yes	Full text of the candidate CV or resume

CriterionDTO

Field	Type	Required	Description
id	string	Yes	Unique criterion identifier
name	string	Yes	Human readable criterion name, for example "Leadership"
description	string	No	Optional detailed description of what you are looking for
weight	number	No	Weight or importance of the criterion, default 1

Example Request

{
  "candidates": [
    {
      "id": "cand_001",
      "name": "Alice Johnson",
      "candidateCV": "Senior software engineer with team leadership experience, founder of a small startup, MS in Computer Science from a top national university..."
    },
    {
      "id": "cand_002",
      "name": "Bob Smith",
      "candidateCV": "Mid level engineer with strong backend experience, no formal leadership responsibilities, BSc in Computer Science..."
    }
  ],
  "criteria": [
    {
      "id": "crit_leadership",
      "name": "Leadership experience",
      "description": "Has led teams, projects, or managed people",
      "weight": 2
    },
    {
      "id": "crit_top_uni",
      "name": "Top university background",
      "description": "Graduated from a top national or global university",
      "weight": 1.5
    },
    {
      "id": "crit_entrepreneur",
      "name": "Entrepreneurship",
      "description": "Has founded or co founded a startup or business",
      "weight": 1
    }
  ]
}

4. Response

Success Response

Status: 200 OK
Content-Type: application/json

Schema

Field	Type	Description
candidates	array of CandidateResultDTO	Per candidate ranking and results

CandidateResultDTO

Field	Type	Description
id	string	Candidate identifier
name	string	Candidate name
rank	number	Rank of the candidate among all candidates, starting 1
totalScore	number	Total calculated score based on criteria and weights
confidence	number	Confidence level from 0 to 100
criteriaResults	array of CriterionResultDTO	Yes or no per criterion with explanations

CriterionResultDTO

Field	Type	Description
criterionId	string	Criterion identifier
criterionName	string	Criterion name
matched	boolean	Whether the criterion is considered met (true) or not (false)
explanation	string	Text explanation why it is matched or not for this candidate

Example Response

{
  "candidates": [
    {
      "id": "cand_001",
      "name": "Alice Johnson",
      "rank": 1,
      "totalScore": 92,
      "confidence": 95,
      "criteriaResults": [
        {
          "criterionId": "crit_leadership",
          "criterionName": "Leadership experience",
          "matched": true,
          "explanation": "CV mentions leading a team of 6 engineers and acting as tech lead on multiple projects."
        },
        {
          "criterionId": "crit_top_uni",
          "criterionName": "Top university background",
          "matched": true,
          "explanation": "Holds an MS in Computer Science from a top ranked national university."
        },
        {
          "criterionId": "crit_entrepreneur",
          "criterionName": "Entrepreneurship",
          "matched": true,
          "explanation": "Founded a small software startup and managed product and growth."
        }
      ]
    },
    {
      "id": "cand_002",
      "name": "Bob Smith",
      "rank": 2,
      "totalScore": 68,
      "confidence": 88,
      "criteriaResults": [
        {
          "criterionId": "crit_leadership",
          "criterionName": "Leadership experience",
          "matched": false,
          "explanation": "CV describes individual contributor roles with no direct leadership responsibilities."
        },
        {
          "criterionId": "crit_top_uni",
          "criterionName": "Top university background",
          "matched": false,
          "explanation": "Bachelor degree in Computer Science is present but the university is not classified as top tier in the model data."
        },
        {
          "criterionId": "crit_entrepreneur",
          "criterionName": "Entrepreneurship",
          "matched": false,
          "explanation": "No mention of founding or co founding a company or startup."
        }
      ]
    }
  ]
}

5. Error Responses

400 Bad Request

Invalid or incomplete input, such as missing candidate CVs or criteria.

{
  "status": 400,
  "error": "Bad Request",
  "message": "Candidates and criteria are required and must be valid."
}

401 Unauthorized

Missing or invalid token.

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Authentication required."
}

500 Internal Server Error

Unexpected failure during processing.

{
  "status": 500,
  "error": "Server Error",
  "message": "An error occurred while ranking candidates."
}

6. Usage Examples

cURL

curl -X POST https://api.supportfinity.com/ai/custom-criteria-ranking \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "candidates": [
      { "id": "cand_001", "name": "Alice", "candidateCV": "..." },
      { "id": "cand_002", "name": "Bob", "candidateCV": "..." }
    ],
    "criteria": [
      { "id": "crit_leadership", "name": "Leadership experience", "weight": 2 },
      { "id": "crit_top_uni", "name": "Top university background", "weight": 1.5 }
    ]
  }'

JavaScript (Fetch)

const rankCandidates = async (payload) => {
  const response = await fetch(
    "https://api.supportfinity.com/ai/custom-criteria-ranking",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP error, status: ${response.status}`);
  }

  return response.json();
};

Python (Requests)

import requests

def rank_candidates(access_token, payload):
    url = "https://api.supportfinity.com/ai/custom-criteria-ranking"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }

    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    return response.json()

7. Notes

The API uses AI to interpret CV text and match it against criteria, then calculates a weighted total score.
Candidates in the response can be assumed to be sorted by rank.
Confidence is an internal measure that reflects how clearly the CV content supports the scoring.
This feature is ideal for building candidate search, shortlisting, and intelligent filtering flows.

SWOT Analysis API

Talent Signals API