curl --request GET \
--url https://cutshort.io/api/v1/search/candidates \
--header 'Authorization: Bearer <token>'import requests
url = "https://cutshort.io/api/v1/search/candidates"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://cutshort.io/api/v1/search/candidates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"results": [
{
"talentCardId": "<string>",
"experience": 123,
"locations": [
"<string>"
],
"currentLocation": "<string>",
"currentCompany": "<string>",
"joiningAvailability": {
"status": "<string>",
"noticePeriodEndsOn": "2023-11-07T05:31:56Z"
},
"currentSalary": 123,
"workHistory": [
"<string>"
],
"education": [
"<string>"
],
"profileSignals": {
"educationPedigree": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"workQuality": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"careerGrowth": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"startupExperience": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"entrepreneurship": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"jobTenure": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"industryTags": [
{
"tag": "<string>",
"label": "<string>",
"score": 123,
"reason": "<string>"
}
]
},
"redactedResumeText": "<string>",
"lastSeen": "2023-11-07T05:31:56Z"
}
],
"page": 123,
"pageSize": 123,
"totalCount": 123,
"searchType": "structured"
}{
"error_code": "<string>",
"error_description": "<string>"
}{
"error_code": "<string>",
"error_description": "<string>"
}{
"error_code": "<string>",
"error_description": "<string>"
}Search talent database
Structured and/or AI/NLP talent search. Hits carry triage data only (headline, experience, profileSignals, redacted resume excerpt) — no names, email, or phone. Use GET /candidates/ for identity (auto-unlocks).
Requires scope search:read. Metered on the workspace searches quota (each page request counts). Rate limits: 10 search + 120 global requests per 60s per API key. At least one search filter is required (q, inresume, locations, experience, salary, profile attributes, or activity); bare pagination-only requests return 400 search_criteria_required.
curl --request GET \
--url https://cutshort.io/api/v1/search/candidates \
--header 'Authorization: Bearer <token>'import requests
url = "https://cutshort.io/api/v1/search/candidates"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://cutshort.io/api/v1/search/candidates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"results": [
{
"talentCardId": "<string>",
"experience": 123,
"locations": [
"<string>"
],
"currentLocation": "<string>",
"currentCompany": "<string>",
"joiningAvailability": {
"status": "<string>",
"noticePeriodEndsOn": "2023-11-07T05:31:56Z"
},
"currentSalary": 123,
"workHistory": [
"<string>"
],
"education": [
"<string>"
],
"profileSignals": {
"educationPedigree": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"workQuality": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"careerGrowth": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"startupExperience": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"entrepreneurship": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"jobTenure": {
"score": 123,
"level": "<string>",
"reason": "<string>"
},
"industryTags": [
{
"tag": "<string>",
"label": "<string>",
"score": 123,
"reason": "<string>"
}
]
},
"redactedResumeText": "<string>",
"lastSeen": "2023-11-07T05:31:56Z"
}
],
"page": 123,
"pageSize": 123,
"totalCount": 123,
"searchType": "structured"
}{
"error_code": "<string>",
"error_description": "<string>"
}{
"error_code": "<string>",
"error_description": "<string>"
}{
"error_code": "<string>",
"error_description": "<string>"
}Authorizations
Workspace-scoped API key. Prefix: cs_live_. Eval keys (self-serve from Cutshort → Settings → Integrations → API Key) can search and get candidate details within small quotas; production keys add job posting and candidate messaging with higher limits.
Query Parameters
NLP / AI search query. Rewritten then embedded for semantic ranking. Can be combined with structured filters.
50000Lucene boolean over full resume text. Use quoted phrases, OR within synonym groups, AND between groups, e.g. ("React" OR "React.js") AND ("TypeScript"). This is the way to express skill requirements — there is no separate skills parameter.
Desired work locations (dash-separated, URL-encoded)
Candidate's current location (same encoding as locations)
Min experience (years, decimal ok)
Max experience (years)
Min current CTC (INR)
Max current CTC (INR). Always include to cap results.
Max days to join (e.g. 30)
true = only candidates on notice period or not working
Education pedigree tiers, dash-separated: tier1plus (IIT/IIM top), tier1, tier2. Example: tier1plus-tier1
Startup background, dash-separated: funded_startup, other_startup
Exclude IT-services background, dash-separated: largeITServices, otherITServices
Entrepreneurship background, dash-separated: cofounder, earlyEmployee
Industry/domain background, dash-separated. Values: banking_and_finance, healthcare, ecommerce, computer_security, travel, edtech_education, gaming, consumer_internet, b2b_saas, software_product, gcc. High-confidence matching is always applied.
'or' = profile attributes (eduPed, startupExp, entrExp, domainTags) match ANY instead of ALL. Default (omitted): all supplied profile attributes must match.
or Candidate activity recency: active-3-months or active-6-months
x >= 1Results per page (default 10, max 20)
1 <= x <= 20