Quickstart

You need an API key first. Approved employers can generate one at Settings → Integrations → API Key — start with Eval access. See Getting API access.

1. Generate an API key

Open Settings → Integrations → API Key
Select Eval access — available to all approved employers
Click Generate API key
Copy the cs_live_… value from the confirmation modal

Need Production access (all scopes)? Your workspace must have production API enabled — email hello@cutshort.io, then choose Production access when generating a key. For API support (questions, integration help, quotas), email engineering@cutshort.io from the email address on your Cutshort account.

2. Search candidates

curl -s -G "https://cutshort.io/api/v1/search/candidates" \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  --data-urlencode "q=senior backend engineer python django" \
  --data-urlencode "minexp=4" \
  --data-urlencode "maxexp=10" \
  --data-urlencode "locations=Bengaluru+%28Bangalore%29" \
  --data-urlencode "page=1"

import requests

API_KEY = "cs_live_YOUR_KEY"
params = {
    "q": "senior backend engineer python django",
    "minexp": "4",
    "maxexp": "10",
    "locations": "Bengaluru (Bangalore)",
    "page": 1,
}

resp = requests.get(
    "https://cutshort.io/api/v1/search/candidates",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params=params,
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(f"Found {data['totalCount']} matches, showing {len(data['results'])} on page 1")
for hit in data["results"]:
    print(hit["experience"], "yrs", hit.get("currentCompany", ""))

const params = new URLSearchParams({
  q: "senior backend engineer python django",
  minexp: "4",
  maxexp: "10",
  locations: "Bengaluru (Bangalore)",
  page: "1",
});

const res = await fetch(
  `https://cutshort.io/api/v1/search/candidates?${params}`,
  { headers: { Authorization: "Bearer cs_live_YOUR_KEY" } }
);
const data = await res.json();
console.log(data.totalCount, data.results.length);

3. Read the response

{
  "results": [
    {
      "talentCardId": "…",
      "experience": 6,
      "currentSalary": 2800000,
      "profileSignals": {
        "educationPedigree": { "score": 3, "level": "tier1plus", "reason": "…" },
        "workQuality": { "score": 3, "level": "high", "reason": "…" }
      },
      "redactedResumeText": "…"
    }
  ],
  "page": 1,
  "pageSize": 10,
  "totalCount": 847,
  "searchType": "ai"
}

pageSize defaults to 10 and accepts up to 20 on the search endpoint.

4. Check usage

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

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

Every meter is a used/limit pair; meters reset at cycleEndsOn.

5. Get contact info (auto-unlock)

After shortlisting a candidate from search, one call gets you their identity, resume text, and a resume file download link. If the candidate is locked for your workspace, this call unlocks them automatically — spending one unlock credit:

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

# Fetch details (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"

See Get candidate details for the full flow.

Search candidates guide — filters, inresume, location encoding
Get candidate details — contact info, resume file, auto-unlock credits
Profile signals — interpret profileSignals on each hit
Post a job, Invite to apply, and Send a message — production keys
Rate limits — burst caps, quotas, and error handling

Getting started

Guides

1. Generate an API key

2. Search candidates

3. Read the response

4. Check usage

5. Get contact info (auto-unlock)

Next

​1. Generate an API key

​2. Search candidates

​3. Read the response

​4. Check usage

​5. Get contact info (auto-unlock)

​Next

1. Generate an API key

2. Search candidates

3. Read the response

4. Check usage

5. Get contact info (auto-unlock)

Next