Search Candidates by Skills, Experience, and Location

The candidate search endpoint is your primary way to discover engineers in Cutshort’s talent pool. You can filter by any combination of skills, years of experience, location, salary expectation, availability, and AI quality score. Results are paginated and sorted by match relevance.

Basic search

curl -X GET 'https://api.cutshort.io/v1/candidates/search?skills=react,nodejs&experience_min=3&location=Bengaluru' \
  -H 'Authorization: Bearer YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.cutshort.io/v1/candidates/search",
    params={
        "skills": "react,nodejs",
        "experience_min": 3,
        "location": "Bengaluru"
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()
print(f"{data['total']} candidates found")

Parameter	Type	Description
`skills`	string (comma-separated)	Required skills (e.g., `python,django,aws`)
`experience_min`	integer	Minimum years of experience
`experience_max`	integer	Maximum years of experience
`location`	string	City name (e.g., `Bengaluru`, `Mumbai`, `Remote`)
`remote_only`	boolean	Set `true` to show only remote-open candidates
`salary_max`	integer	Maximum salary expectation in INR (annual)
`quality_score_min`	integer (0–100)	Minimum AI quality score
`availability`	string	One of `active`, `open`, or `active,open`
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (max: 50, default: 20)

Response example

{
  "total": 412,
  "page": 1,
  "per_page": 20,
  "data": [
    {
      "id": "cand_8f3kL9mN",
      "name": "Priya Menon",
      "headline": "Senior React Developer",
      "location": "Bengaluru",
      "experience_years": 5,
      "skills": ["React", "Node.js", "TypeScript"],
      "quality_score": 84,
      "availability": "active",
      "salary_expectation_min": 1800000,
      "salary_expectation_max": 2400000,
      "profile_url": "https://cutshort.io/candidate/priya-menon"
    }
  ]
}

Filtering by quality score

The quality_score_min parameter filters candidates by Cutshort’s AI-computed quality score, which evaluates profile completeness, skill depth, career trajectory, and engagement signals. Scores range from 0 to 100.

Use quality_score_min=70 for a strong signal-to-noise ratio. Use quality_score_min=85 for senior or leadership roles.

Pagination

Use the page and per_page parameters to navigate through large result sets. The total field in the response tells you the full count of matching candidates. Each page returns up to 50 results. To iterate through all pages, increment page until you have collected total records:

import requests

all_candidates = []
page = 1

while True:
    response = requests.get(
        "https://api.cutshort.io/v1/candidates/search",
        params={
            "skills": "python,django",
            "experience_min": 3,
            "page": page,
            "per_page": 50
        },
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    )
    data = response.json()
    all_candidates.extend(data["data"])

    if len(all_candidates) >= data["total"]:
        break

    page += 1

print(f"Fetched {len(all_candidates)} candidates in total")

Best practices

Prefer specific skill names (e.g., react not frontend). Combine availability=active,open with quality_score_min=65 for best response rates.

Get Started

Core Concepts

Guides

MCP Server

Search Candidates by Skills, Experience, and Location

Basic search

Available search filters

Response example

Filtering by quality score

Best practices

​Basic search

​Available search filters

​Response example

​Filtering by quality score

​Pagination

​Best practices

Basic search

Available search filters

Response example

Filtering by quality score

Pagination

Best practices