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

> Contact info, resume file, and auto-unlock credits

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.

<Note>
  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`.
</Note>

## Typical flow

```mermaid theme={null}
sequenceDiagram
  participant You
  participant Search as GET /search/candidates
  participant Usage as GET /usage
  participant Detail as GET /candidates/:id

  You->>Search: Find talentCardId
  Search-->>You: profileSignals, redactedResumeText (no contacts)
  You->>Usage: Check apiUnlocks used/limit
  Usage-->>You: credits remaining
  You->>Detail: Fetch shortlisted candidate
  Detail-->>You: email, phone, resume (unlockedNow: true, 1 credit)
  You->>Detail: Fetch same candidate again later
  Detail-->>You: same data (unlockedNow: false, no charge)
```

1. **Search** — pick `talentCardId` values from [Search candidates](/guides/search-candidates).
2. **Shortlist using triage data** — use `profileSignals` and `redactedResumeText` on search hits; do not fetch details speculatively.
3. **Check credits** — `GET /usage` → `apiUnlocks` (`used` vs `limit`).
4. **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/{talentCardId}

```
GET /api/v1/candidates/{talentCardId}
```

**Scope:** `candidates:read`

**Rate limits:** 30 sensitiveRead + 120 global requests per 60s per API key.

### Response

```json theme={null}
{
  "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                    |

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

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

```bash theme={null}
curl -s "https://cutshort.io/api/v1/usage" \
  -H "Authorization: Bearer cs_live_YOUR_KEY"
```

```json theme={null}
{
  "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

```bash theme={null}
# 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](/guides/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.

## Related

* [Search candidates](/guides/search-candidates) — find `talentCardId` values
* [Invite to apply](/guides/invite-to-apply) — outreach invite (no unlock needed)
* [Rate limits](/guides/rate-limits) — burst caps and quotas
* [Authentication](/authentication) — eval vs production key scopes