> ## 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. # 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/{talentCardId} 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. ## OpenAPI ````yaml /openapi/public-api-v1.json get /search/candidates openapi: 3.1.0 info: title: Cutshort Public API v1 version: 1.0.0 description: >- Programmatic access to Cutshort's tech talent database. All endpoints require `Authorization: Bearer cs_live_`. **Core flow:** search candidates → get candidate details (auto-unlock) → post a job → invite to apply (first contact) → list applications → send message (in-thread follow-up). servers: - url: https://cutshort.io/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Search description: Talent database search - name: Candidates description: Candidate detail with auto-unlock (contact info + resume) - name: Jobs description: Job posting and listing - name: Outreach description: >- Candidate outreach: first-contact invite to apply, and in-thread follow-up messages - name: Usage description: Cycle usage meters and quotas - name: Stages description: Job pipeline stages and counts - name: Applications description: List applications and move them between pipeline stages paths: /search/candidates: get: tags: - Search summary: Search talent database description: >- 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/{talentCardId} 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. operationId: searchCandidates parameters: - name: q in: query schema: type: string maxLength: 50000 description: >- NLP / AI search query. Rewritten then embedded for semantic ranking. Can be combined with structured filters. - name: inresume in: query schema: type: string description: >- Lucene 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. - name: locations in: query schema: type: string description: Desired work locations (dash-separated, URL-encoded) - name: currlocation in: query schema: type: string description: Candidate's current location (same encoding as locations) - name: minexp in: query schema: type: string description: Min experience (years, decimal ok) - name: maxexp in: query schema: type: string description: Max experience (years) - name: minsal in: query schema: type: string description: Min current CTC (INR) - name: maxsal in: query schema: type: string description: Max current CTC (INR). Always include to cap results. - name: canjoinin in: query schema: type: string description: Max days to join (e.g. 30) - name: onNoticePeriodOrNotWorking in: query schema: type: string description: true = only candidates on notice period or not working - name: eduPed in: query schema: type: string description: >- Education pedigree tiers, dash-separated: tier1plus (IIT/IIM top), tier1, tier2. Example: tier1plus-tier1 - name: startupExp in: query schema: type: string description: 'Startup background, dash-separated: funded_startup, other_startup' - name: not_itExp in: query schema: type: string description: >- Exclude IT-services background, dash-separated: largeITServices, otherITServices - name: entrExp in: query schema: type: string description: >- Entrepreneurship background, dash-separated: cofounder, earlyEmployee - name: domainTags in: query schema: type: string description: >- 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. - name: profileAttributesMode in: query schema: type: string enum: - or description: >- 'or' = profile attributes (eduPed, startupExp, entrExp, domainTags) match ANY instead of ALL. Default (omitted): all supplied profile attributes must match. - name: activity in: query schema: type: string description: 'Candidate activity recency: active-3-months or active-6-months' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/pageSizeLimited' responses: '200': description: Search results (index-served triage hits; no identity fields) content: application/json: schema: type: object properties: results: type: array items: $ref: '#/components/schemas/SearchCandidateHit' page: type: integer pageSize: type: integer description: Requested page size (default 10, max 20) totalCount: type: integer searchType: type: string enum: - structured - ai '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: page: name: page in: query schema: type: integer default: 1 minimum: 1 pageSizeLimited: name: pageSize in: query schema: type: integer default: 10 minimum: 1 maximum: 20 description: Results per page (default 10, max 20) schemas: SearchCandidateHit: type: object description: >- Index-served search hit. No identity or lock fields — use GET /candidates/{talentCardId} for identity (auto-unlocks). properties: talentCardId: type: string experience: type: number description: Total experience in years locations: type: array items: type: string description: Desired work locations currentLocation: type: string currentCompany: type: string joiningAvailability: type: object description: >- Joining availability. status is immediate | on_notice_period | not_resigned (or null if unknown). canJoinHowSoonDays is not included on search hits. properties: status: type: string nullable: true noticePeriodEndsOn: type: string format: date-time nullable: true currentSalary: type: number description: Current annual salary (INR, normalized) workHistory: type: array items: type: string description: >- Compact work history, most recent first (max 8), e.g. "Senior Engineer — Flipkart (2021–2024)" education: type: array items: type: string description: Compact education list (max 4), e.g. "B.Tech, IIT Delhi (2018)" profileSignals: $ref: '#/components/schemas/ProfileSignals' redactedResumeText: type: string description: Identity-stripped resume excerpt, capped ~4000 chars lastSeen: type: string format: date-time nullable: true description: Candidate last seen on Cutshort ProfileSignals: type: object description: >- AI-evaluated profile signals. Each scalar field is { score, level, reason } or null (null = not evaluated, not a negative signal). properties: educationPedigree: $ref: '#/components/schemas/ProfileSignal' workQuality: $ref: '#/components/schemas/ProfileSignal' careerGrowth: $ref: '#/components/schemas/ProfileSignal' startupExperience: $ref: '#/components/schemas/ProfileSignal' entrepreneurship: $ref: '#/components/schemas/ProfileSignal' jobTenure: $ref: '#/components/schemas/ProfileSignal' industryTags: type: array items: $ref: '#/components/schemas/IndustryTag' ApiError: type: object properties: error_code: type: string error_description: type: string ProfileSignal: type: object nullable: true properties: score: type: number level: type: string reason: type: string nullable: true IndustryTag: type: object properties: tag: type: string label: type: string score: type: number reason: type: string nullable: true responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiError' Forbidden: description: Insufficient scope (e.g. eval key calling a production-only endpoint) content: application/json: schema: $ref: '#/components/schemas/ApiError' TooManyRequests: description: >- Rate limit (error_code `rate_limit_exceeded`, `Retry-After` header) or cycle quota exhausted (`api_unlock_limit_reached`, `api_search_limit_reached`, `api_message_limit_reached`, `search_throttled`). Check GET /usage for used/limit. content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- 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. ````