Candidate Search API v1

V1 has two public endpoints. Use /public/search to find candidates with a query plus optional filters. Use /public/usage to check your remaining daily quota without spending it.

Send your API key with the x-api-key header or as an Authorization: Bearer token. This is the same CazVid Developer API key as the Job Builder API - one key works for both products. Keys belong to an organization; org owners and admins manage them in the app under Profile > Developer API. Plaintext keys are shown once when created and stored hash-only by CazVid. Treat keys as secrets: do not put them in frontend code, mobile apps, screenshots, logs, or support messages.

x-api-key: cazvid_jb_...
Authorization: Bearer cazvid_jb_...
Content-Type: application/json

POST /public/search takes a required query (2 to 300 characters) plus optional structured filters. Filters narrow the same candidate pool the in-app recruiter search serves. Send page and pageSize to page through results; pageSize is capped at 25 and page at 100.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/candidate-search/public/search \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "bilingual customer support agent in Mexico City",
    "location": "Mexico City, Mexico",
    "remote": true,
    "requireVideo": true,
    "language": "en",
    "page": 1,
    "pageSize": 10
  }'

Each result is a public, scrubbed candidate profile. Nullable fields are omitted or null when CazVid does not have that data. candidateId is an opaque, stable pc1. token, not a raw platform id and not reversible by callers. cazumeUrl is present only when the candidate has published a public Cazume profile.

{
  "results": [
    {
      "candidateId": "pc1.aGVsbG8td29ybGQ",
      "displayName": "Maria G.",
      "headline": "Bilingual Customer Support Specialist",
      "summary": "Five years supporting SaaS customers in English and Spanish.",
      "topSkills": ["Customer support", "Zendesk", "Bilingual (EN/ES)"],
      "matchedSkills": ["Customer support", "Bilingual (EN/ES)"],
      "matchTier": "local",
      "locationName": "Mexico City, Mexico",
      "countryCode": "MX",
      "isRemote": true,
      "language": "en",
      "hasVideo": true,
      "videoUrl": "https://ik.imagekit.io/cazvid/videos/example.mp4",
      "thumbnailUrl": "https://ik.imagekit.io/cazvid/thumbs/example.jpg",
      "avatarUrl": "https://ik.imagekit.io/cazvid/avatars/example.jpg",
      "cazumeUrl": "https://cazvid.com/cazume/maria-g",
      "updatedAt": "2026-07-01T12:30:00.000Z"
    }
  ],
  "hasMore": true,
  "page": 1,
  "pageSize": 10
}

The response wraps the results with pagination metadata. This API paginates on hasMore only - there is no total count.

• results - the candidate profiles for this page.
• hasMore - true when another page exists. Request the next page by incrementing page.
• page - the echoed 1-based page number.
• pageSize - the echoed page size.
• There is no total-count field. Do not expect a total or count: keep requesting pages while hasMore is true.

GET /public/usage returns the calling organization's daily Candidate Search quota. It uses the same authentication as search and does not count against the quota, so you can poll it before a batch to avoid 429 responses. Polling is throttled to 60 requests per minute per API key; exceeding it returns the standard 429 shape with details.period set to minute.

curl https://aio-backend-prod.cazvid.app/api/v3.0/candidate-search/public/usage \
  -H "x-api-key: cazvid_jb_..."

{
  "dailyQuota": 100,
  "used": 12,
  "remaining": 88,
  "resetsAt": "2026-07-08T00:00:00.000Z",
  "period": "utc_day"
}

Error responses use stable errorCode values so integrations do not need to parse prose messages. Every error echoes the request path; 429 responses add retryAfter, the number of seconds until the limit window resets. A 429 from the daily quota carries details.period of utc_day; a 429 from the per-minute burst or usage throttle carries minute.

{
  "statusCode": 429,
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "message": "Daily Candidate Search API quota exceeded.",
  "details": {
    "limit": 100,
    "period": "utc_day"
  },
  "retryAfter": 21600,
  "path": "/api/v3.0/candidate-search/public/search"
}

Candidate data is provided to serve the end user's request in front of you, not to be copied or resold. By using this API you agree to the following. These terms may be replaced by formal API terms at general availability.

• No bulk mirroring or redistribution. Do not copy the candidate index into your own store or build a competing directory or dataset from it.
• No retention beyond serving the request. Hold results only as long as needed to answer the request in front of you; do not build a persistent shadow copy of candidate profiles.
• No resale. Candidate profiles and any fields derived from them may not be sold, sublicensed, or redistributed.
• Contact candidates only through CazVid. Results carry no contact details; reach a candidate through their public Cazume profile or the CazVid app, never off-platform.
• No quota circumvention. Do not use multiple keys, organizations, or accounts to evade the per-organization daily quota or the per-minute burst limit.

• V1 quota is 100 successful search calls per organization per UTC day. This is a separate quota from the Job Builder API.
• A per-organization burst limit of 20 searches per minute protects the shared search backend. Exceeding it returns 429 with details.period set to minute.
• pageSize is capped at 25 and page at 100. Requests above those bounds return 400 VALIDATION_ERROR.
• Results carry no contact details (no email, phone, or LinkedIn) and no raw platform ids. Reach candidates through the CazVid app or their Cazume profile.
• Rotate keys by creating a new key, updating your integration, then revoking the old key. The same key serves the Job Builder API too.

Prefer to drive candidate search from an AI agent instead of raw HTTP? The CazVid MCP server exposes search_candidates (plus list_api_usage) to Claude Code, Claude.ai, ChatGPT, Cursor, and VS Code, using this same API key and daily quota.