Search candidates

GET /search/candidates is the primary v1 endpoint. It searches Cutshort’s talent database and returns 10 hits per page with triage data — no identity or contact fields.

Response fields

Each hit includes:

Field	Description
`talentCardId`	Stable ID for follow-up API calls — see Get candidate details
`experience`	Total years
`locations`	Desired work locations
`currentLocation`, `currentCompany`	Current placement
`joiningAvailability`	`{ status, noticePeriodEndsOn }` — status is `immediate` / `on_notice_period` / `not_resigned`
`lastSeen`	Last activity on Cutshort (ISO timestamp)
`currentSalary`	Annual INR
`workHistory`	Compact strings, most recent first (max 8)
`education`	Compact degree/college strings (max 4)
`profileSignals`	AI-evaluated pedigree, quality, industry — see Profile signals
`redactedResumeText`	Identity-stripped resume excerpt (~4k chars)

Use profileSignals and redactedResumeText together to judge fit without contact details. When you want email, phone, or the resume file, call Get candidate details — it auto-unlocks the candidate (one credit).

AI / NLP search

At least one search filter is required (q, inresume, location/experience/salary, profile attributes, or activity). Bare pagination-only requests are rejected with 400 search_criteria_required. Add q (up to 20,000 characters; inputs above 50,000 are rejected) for semantic ranking:

GET /search/candidates?q=ML engineer with startup pedigree&minexp=3&maxexp=8

Cutshort rewrites q with a role-summary prompt, embeds it, and runs kNN search. Short phrases like python developer work. Combine q with structured filters — filters narrow the pool, q ranks within it. Response includes searchType: "ai" when q is present, otherwise "structured".

Skill search — use `inresume`

Skill requirements are expressed with inresume — a Lucene boolean query over the full resume text. It catches every mention (tagged skills, job descriptions, projects), so recall is much higher than tag-based filtering. There is no separate skills parameter.

Good `inresume` examples

(python OR django OR fastapi) AND (pytorch OR tensorflow OR sklearn OR "machine learning")

(java OR kotlin OR go) AND (microservices OR "distributed systems")

(react OR "react.js" OR nextjs) AND (typescript) AND (jest OR cypress)

Rules:

Use uppercase AND / OR / NOT
Quote phrases: "machine learning", "system design"
Within a group, list synonyms and abbreviations with OR (ML OR "machine learning")
Keep 2–4 skill groups — more groups reduce recall
Avoid version suffixes: python, not python 3.10
Do not URL-encode manually; pass the raw expression

Location encoding

Param	Meaning
`locations`	Where the candidate should be willing to work
`currlocation`	Candidate’s current city

Encoding:

Spaces → + (e.g. Navi+Mumbai)
Multiple cities → dash-separated (Mumbai-Pune)
Bangalore → Bengaluru+%28Bangalore%29

Experience and salary

Always pass both bounds when filtering experience:

Param	Notes
`minexp` / `maxexp`	Years; decimals OK (e.g. `4.5`)
`minsal` / `maxsal`	Current CTC in INR

If only one experience bound is sent, the API fills the other automatically.

Availability

Param	Meaning
`canjoinin`	Max days to join (e.g. `30`) — includes candidates on notice with enough time left
`onNoticePeriodOrNotWorking`	`true` = only candidates serving notice or not working (stricter than `canjoinin`)

Param	Values (dash-separated)	Meaning
`eduPed`	`tier1plus`, `tier1`, `tier2`	College pedigree
`startupExp`	`funded_startup`, `other_startup`	Startup background
`not_itExp`	`largeITServices`, `otherITServices`	Exclude IT-services background
`entrExp`	`cofounder`, `earlyEmployee`	Entrepreneurship
`domainTags`	`banking_and_finance`, `healthcare`, `ecommerce`, `computer_security`, `travel`, `edtech_education`, `gaming`, `consumer_internet`, `b2b_saas`, `software_product`, `gcc`	Industry / domain background (high-confidence matching)
`activity`	`active-3-months`, `active-6-months`	Recency on Cutshort

These filters correspond to fields in profileSignals on each hit. Dash-separated values within one param are OR’d (e.g. eduPed=tier1plus-tier1 = either tier).

Combining profile attributes: AND vs OR

By default, supplying more than one of eduPed, startupExp, entrExp, domainTags requires a candidate to match all of them. Add profileAttributesMode=or to match any:

# AND (default): tier1plus education AND cofounder background
eduPed=tier1plus&entrExp=cofounder

# OR: tier1plus education OR cofounder background
eduPed=tier1plus&entrExp=cofounder&profileAttributesMode=or

profileAttributesMode=or affects only these four params. All other filters (location, experience, salary, inresume, availability, activity) always stay ANDed.

Pagination

Param	Default	Max
`page`	1	—
`pageSize`	10	20

Search discipline

Run searches sequentially — not in parallel
Review each page before refining
Avoid near-identical queries (overlapping results waste quota)
When exploring multiple angles, use disjoint slices (different experience bands or locations)

See Rate limits for burst caps.

Example — ML engineer in Bangalore

curl -G "https://cutshort.io/api/v1/search/candidates" \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  --data-urlencode 'q=ML model training production experience' \
  --data-urlencode 'minexp=3' \
  --data-urlencode 'maxexp=8' \
  --data-urlencode 'eduPed=tier1plus-tier1' \
  --data-urlencode 'locations=Bengaluru+%28Bangalore%29' \
  --data-urlencode 'inresume=(python OR pytorch OR tensorflow) AND ("machine learning" OR ML)'

Getting started

Guides

Response fields

AI / NLP search

Skill search — use `inresume`

Good `inresume` examples

Location encoding

Experience and salary

Availability

Profile attribute filters

Combining profile attributes: AND vs OR

Search discipline

Example — ML engineer in Bangalore

​Response fields

​AI / NLP search

​Skill search — use inresume

​Good inresume examples

​Location encoding

​Experience and salary

​Availability

​Profile attribute filters

​Combining profile attributes: AND vs OR

​Pagination

​Search discipline

​Example — ML engineer in Bangalore

Response fields

AI / NLP search

Skill search — use `inresume`

Good `inresume` examples

Location encoding

Experience and salary

Availability

Profile attribute filters

Combining profile attributes: AND vs OR

Pagination

Search discipline

Example — ML engineer in Bangalore