POST /sourcing/shortlist — Generate Candidate Shortlist

The shortlist endpoint triggers Cutshort’s AI matching engine to generate a ranked list of best-fit candidates for a specific job. The engine uses the job’s description, required skills, experience range, and location to semantically match and rank candidates from the full talent pool.

Endpoint

POST https://api.cutshort.io/v1/sourcing/shortlist

Request Body

string

required

The ID of the job to generate a shortlist for.

integer

Maximum number of candidates to return. Max: 50. Default: 20.

integer

Minimum quality score filter. Accepts values from 0 to 100. Only candidates with a quality score at or above this threshold are included.

string

Filter candidates by availability status. Accepted values: active, open, or active,open.

Example Request

curl -X POST 'https://api.cutshort.io/v1/sourcing/shortlist' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "job_id": "job_4xRt2wPv",
    "limit": 15,
    "quality_score_min": 70,
    "availability": "active,open"
  }'

import requests

response = requests.post(
    "https://api.cutshort.io/v1/sourcing/shortlist",
    json={
        "job_id": "job_4xRt2wPv",
        "limit": 15,
        "quality_score_min": 70,
        "availability": "active,open"
    },
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
)
shortlist = response.json()
print(f"Shortlisted {len(shortlist['data'])} candidates")

Response

Returns 200 OK with a JSON body.

{
  "job_id": "job_4xRt2wPv",
  "total": 15,
  "data": [
    {
      "rank": 1,
      "match_score": 92,
      "candidate": {
        "id": "cand_8f3kL9mN",
        "name": "Priya Menon",
        "headline": "Senior Python Engineer",
        "location": "Bengaluru",
        "experience_years": 5,
        "quality_score": 82,
        "availability": "active",
        "skills": ["Python", "Django", "PostgreSQL", "AWS"]
      },
      "match_reasons": [
        "5 years Python experience matches requirement",
        "B2C product background aligns with role context",
        "PostgreSQL and AWS skills validated"
      ]
    }
  ]
}

Response Fields

string

The job this shortlist belongs to.

integer

Number of candidates in the shortlist.

integer

Rank of the candidate in the shortlist. 1 indicates the best match.

integer

A score from 0 to 100 indicating how well the candidate matches this specific job.

object

A summary of the candidate’s profile, identical in shape to a search result object.

array of strings

Human-readable explanations for why this candidate was matched to the job.

Use match_reasons to explain shortlist selections to hiring managers. The reasons are designed to be human-readable.

Overview

Candidates

Jobs

Sourcing

Webhooks

POST /sourcing/shortlist — Generate Candidate Shortlist

Endpoint

Request Body

Example Request

Response

Response Fields

​Endpoint

​Request Body

​Example Request

​Response

​Response Fields

Endpoint

Request Body

Example Request

Response

Response Fields