> ## 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.

# Get candidate detail (auto-unlock)

> Returns full candidate identity, the actual resume (text + signed file download URL), and structured profile. If the candidate is locked for your workspace, this call unlocks them first — spending **one unlock credit** against the workspace unlock quota (check GET /usage). Already-unlocked candidates are never re-charged.

Requires scope `candidates:read` (eval + production keys). Rate limits: 30 sensitiveRead + 120 global requests per 60s per API key.



## OpenAPI

````yaml /openapi/public-api-v1.json get /candidates/{talentCardId}
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_<key>`.


    **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:
  /candidates/{talentCardId}:
    get:
      tags:
        - Candidates
      summary: Get candidate detail (auto-unlock)
      description: >-
        Returns full candidate identity, the actual resume (text + signed file
        download URL), and structured profile. If the candidate is locked for
        your workspace, this call unlocks them first — spending **one unlock
        credit** against the workspace unlock quota (check GET /usage).
        Already-unlocked candidates are never re-charged.


        Requires scope `candidates:read` (eval + production keys). Rate limits:
        30 sensitiveRead + 120 global requests per 60s per API key.
      operationId: getCandidateDetail
      parameters:
        - name: talentCardId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Unlocked candidate detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    CandidateDetail:
      type: object
      description: >-
        Unlocked candidate detail (GET /candidates/{talentCardId} auto-unlocks
        locked candidates).
      properties:
        talentCardId:
          type: string
        lockStatus:
          type: string
          enum:
            - locked
            - unlocked
        unlockedNow:
          type: boolean
          description: >-
            true when this call spent an unlock credit; false when the candidate
            was already unlocked
        displayName:
          type: string
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        originalResumeFileName:
          type: string
        originalResumeDownloadUrl:
          type: string
          description: >-
            Signed URL to download the candidate's actual resume file. Expires
            after 1 hour — re-fetch for a fresh link (free once unlocked).
        profile:
          type: object
          description: >-
            Structured profile: full resume text (~8k chars), past companies
            with work summaries, education, skills
    ApiError:
      type: object
      properties:
        error_code:
          type: string
        error_description:
          type: string
  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'
    NotFound:
      description: Resource not found
      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.

````