> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cutshort.io/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /sourcing/shortlist — Generate Candidate Shortlist

> Request an AI-generated candidate shortlist for a job. Cutshort ranks the best-fit candidates by match score from a pool of 4M+ verified profiles.

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

```http theme={null}
POST https://api.cutshort.io/v1/sourcing/shortlist
```

## Request Body

<ParamField body="job_id" type="string" required>
  The ID of the job to generate a shortlist for.
</ParamField>

<ParamField body="limit" type="integer">
  Maximum number of candidates to return. Max: `50`. Default: `20`.
</ParamField>

<ParamField body="quality_score_min" type="integer">
  Minimum quality score filter. Accepts values from `0` to `100`. Only candidates with a quality score at or above this threshold are included.
</ParamField>

<ParamField body="availability" type="string">
  Filter candidates by availability status. Accepted values: `active`, `open`, or `active,open`.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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")
  ```
</CodeGroup>

## Response

Returns `200 OK` with a JSON body.

```json theme={null}
{
  "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

<ResponseField name="job_id" type="string">
  The job this shortlist belongs to.
</ResponseField>

<ResponseField name="total" type="integer">
  Number of candidates in the shortlist.
</ResponseField>

<ResponseField name="data[].rank" type="integer">
  Rank of the candidate in the shortlist. `1` indicates the best match.
</ResponseField>

<ResponseField name="data[].match_score" type="integer">
  A score from `0` to `100` indicating how well the candidate matches this specific job.
</ResponseField>

<ResponseField name="data[].candidate" type="object">
  A summary of the candidate's profile, identical in shape to a search result object.
</ResponseField>

<ResponseField name="data[].match_reasons" type="array of strings">
  Human-readable explanations for why this candidate was matched to the job.
</ResponseField>

<Tip>
  Use `match_reasons` to explain shortlist selections to hiring managers. The reasons are designed to be human-readable.
</Tip>