Get candidate details

Search hits give you triage data only — no name, email, or phone. To contact a candidate you found in search, call GET /candidates/{talentCardId}. If the candidate is still locked for your workspace, this call unlocks them automatically — spending one unlock credit — and returns the full detail in the same response. There is no separate unlock endpoint.

Available to eval and production keys (candidates:read). Eval workspaces get 10 unlock credits per cycle by default; production workspaces get higher grants. Check GET /usage.

Typical flow

Search — pick talentCardId values from Search candidates.
Shortlist using triage data — use profileSignals and redactedResumeText on search hits; do not fetch details speculatively.
Check credits — GET /usage → apiUnlocks (used vs limit).
Fetch details — GET /candidates/{talentCardId} for each candidate you want to contact. Locked candidates are unlocked on the spot (irreversible, one credit each).

GET /candidates/

GET /api/v1/candidates/{talentCardId}

Scope: candidates:read Rate limits: 30 sensitiveRead + 120 global requests per 60s per API key.

Response

{
  "talentCardId": "64f1a2b3c4d5e6f7a8b9c0d1",
  "lockStatus": "unlocked",
  "unlockedNow": true,
  "displayName": "Priya Sharma",
  "email": "priya@example.com",
  "phone": "+919876543210",
  "originalResumeFileName": "Priya_Sharma_Resume.pdf",
  "originalResumeDownloadUrl": "https://s3.amazonaws.com/…/original.pdf?X-Amz-…",
  "profile": {
    "text_from_resume": "…full resume text…",
    "past_companies": ["…"]
  }
}

Field	Meaning
`unlockedNow`	`true` = this call spent one unlock credit; `false` = candidate was already unlocked (no charge)
`originalResumeDownloadUrl` + `originalResumeFileName`	Signed link to the candidate’s uploaded resume file (PDF/DOC) — same as Download resume in the Cutshort UI
`profile`	Structured profile including the actual resume text (~8k chars), past companies, education

Resume file URLs expire after 1 hour. Re-call the endpoint for fresh links — repeat calls on unlocked candidates are free.

Unlock credits

Each new unlock counts against your workspace’s apiUnlocks meter for the current cycle. Already-unlocked candidates never re-charge. Check remaining credits:

curl -s "https://cutshort.io/api/v1/usage" \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

{
  "apiUnlocks": { "used": 3, "limit": 10 },
  "searches": { "used": 40, "limit": 100 },
  "messages": { "used": 2, "limit": 20 },
  "cycleEndsOn": "2026-08-15T00:00:00.000Z"
}

When API credits are exhausted, GET /candidates/{id} on a locked candidate returns 429 with error_code: api_unlock_limit_reached. Already-unlocked candidates keep working. If the API quota still shows remaining credits but unlock fails, the workspace’s product plan unlock pool may be exhausted. This returns 429 plan_unlock_limit_reached — a separate limit from the API quota.

Example — search, then fetch

# 1. Search
curl -s -G "https://cutshort.io/api/v1/search/candidates" \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  --data-urlencode "q=senior python backend" \
  --data-urlencode "minexp=4" \
  --data-urlencode "page=1"

# 2. Check credits
curl -s "https://cutshort.io/api/v1/usage" \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

# 3. Fetch details for the shortlist (auto-unlocks; 1 credit per new candidate)
curl -s "https://cutshort.io/api/v1/candidates/TALENT_CARD_ID" \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

Best practices

Shortlist from search first — use Profile signals and redactedResumeText; only fetch details for candidates you intend to contact.
Confirm before fetching in bulk — each new candidate spends a credit and unlocking cannot be undone.
Check apiUnlocks before batch fetches.
Fetch sequentially — not in parallel — to stay within rate limits and make quota errors easier to handle.

Search candidates — find talentCardId values
Invite to apply — outreach invite (no unlock needed)
Rate limits — burst caps and quotas
Authentication — eval vs production key scopes

Getting started

Guides

Typical flow

GET /candidates/

Response

Unlock credits

Example — search, then fetch

Best practices

​Typical flow

​GET /candidates/

​Response

​Unlock credits

​Example — search, then fetch

​Best practices

​Related

Typical flow

GET /candidates/

Response

Unlock credits

Example — search, then fetch

Best practices

Related