{"openapi":"3.0.0","info":{"title":"CazVid Candidate Search Public API","version":"1.0.0","description":"Search CazVid candidate profiles with structured filters. See https://cazvid.com/api/candidate-search/v1 for guides and examples."},"servers":[{"url":"https://aio-backend-prod.cazvid.app"}],"paths":{"/api/v3.0/candidate-search/public/search":{"post":{"operationId":"candidateSearchPublicSearch","summary":"Search candidate profiles with structured filters.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key>. Results carry NO contact information (no email/phone/linkedin); reach a candidate through the CazVid app using the returned candidateId or cazumeUrl. Limited to 20 searches per minute per organization plus a daily quota of 100 per UTC day.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateSearchRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateSearchResponseDto"}}}},"400":{"description":"The request body failed validation, or a malformed organizationId or workspaceId query parameter was supplied (not a 24-character hex ObjectId). details lists each offending field, and is an empty array for the malformed-query-parameter case.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"examples":{"VALIDATION_ERROR":{"summary":"A field failed validation","value":{"statusCode":400,"errorCode":"VALIDATION_ERROR","message":"query must be at least 2 characters","path":"/api/v3.0/candidate-search/public/search","details":[{"field":"query","message":"query must be at least 2 characters"}]}}}}}},"401":{"description":"Authentication failed: no API key was presented, or the presented key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}}},"examples":{"API_KEY_MISSING":{"summary":"No API key presented","value":{"statusCode":401,"errorCode":"API_KEY_MISSING","message":"Missing API key. Send it with x-api-key or Authorization: Bearer <key>.","path":"/api/v3.0/candidate-search/public/search"}},"API_KEY_INVALID":{"summary":"Key not recognized","value":{"statusCode":401,"errorCode":"API_KEY_INVALID","message":"API key is invalid.","path":"/api/v3.0/candidate-search/public/search"}},"API_KEY_EXPIRED":{"summary":"Key past its expiry","value":{"statusCode":401,"errorCode":"API_KEY_EXPIRED","message":"API key has expired.","path":"/api/v3.0/candidate-search/public/search"}},"API_KEY_REVOKED":{"summary":"Key revoked","value":{"statusCode":401,"errorCode":"API_KEY_REVOKED","message":"API key has been revoked.","path":"/api/v3.0/candidate-search/public/search"}}}}}},"403":{"description":"The key authenticated but is not allowed to run this request: the organization lacks a qualifying paid plan, the key is missing the candidate-search:read scope, or it cannot access the resolved organization or workspace.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}}},"examples":{"PLAN_REQUIRED":{"summary":"Organization is not on a qualifying paid plan","value":{"statusCode":403,"errorCode":"PLAN_REQUIRED","message":"Candidate Search API access requires a Platinum, Diamond, or Enterprise plan.","path":"/api/v3.0/candidate-search/public/search"}},"SCOPE_FORBIDDEN":{"summary":"Key lacks the candidate-search:read scope","value":{"statusCode":403,"errorCode":"SCOPE_FORBIDDEN","message":"API key scope is not allowed","path":"/api/v3.0/candidate-search/public/search"}},"ORG_ACCESS_DENIED":{"summary":"Key cannot access the resolved organization","value":{"statusCode":403,"errorCode":"ORG_ACCESS_DENIED","message":"API key cannot access this organization","path":"/api/v3.0/candidate-search/public/search"}},"WORKSPACE_ACCESS_DENIED":{"summary":"Key cannot access the resolved workspace","value":{"statusCode":403,"errorCode":"WORKSPACE_ACCESS_DENIED","message":"API key cannot access this workspace","path":"/api/v3.0/candidate-search/public/search"}}}}}},"429":{"description":"A rate limit was exceeded. Two independent limits apply to search: a per-minute burst limit (20 per organization) and a daily quota (100 per UTC day). retryAfter is the whole number of seconds to wait.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"object","required":["limit","period"],"properties":{"limit":{"type":"integer"},"period":{"type":"string","enum":["utc_day","minute"]}}},"retryAfter":{"type":"integer","description":"Whole seconds to wait before retrying."}}},"examples":{"daily_quota":{"summary":"Daily quota of 100 per UTC day exhausted","value":{"statusCode":429,"errorCode":"RATE_LIMIT_EXCEEDED","message":"Daily Candidate Search API quota exceeded.","path":"/api/v3.0/candidate-search/public/search","retryAfter":3600,"details":{"limit":100,"period":"utc_day"}}},"burst":{"summary":"Burst limit of 20 per minute exceeded","value":{"statusCode":429,"errorCode":"RATE_LIMIT_EXCEEDED","message":"Candidate Search API burst limit exceeded. Slow down and retry shortly.","path":"/api/v3.0/candidate-search/public/search","retryAfter":20,"details":{"limit":20,"period":"minute"}}}}}}},"500":{"description":"An unexpected error occurred while running the search. The underlying cause is intentionally hidden from the response body.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}}},"examples":{"CANDIDATE_SEARCH_API_ERROR":{"summary":"Unexpected server error","value":{"statusCode":500,"errorCode":"CANDIDATE_SEARCH_API_ERROR","message":"Candidate Search API request failed.","path":"/api/v3.0/candidate-search/public/search"}}}}}},"504":{"description":"The upstream candidate search did not complete in time. Retrying with a simpler or more specific query is safe.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}}},"examples":{"SEARCH_TIMEOUT":{"summary":"Upstream search timed out","value":{"statusCode":504,"errorCode":"SEARCH_TIMEOUT","message":"The candidate search took too long. Retrying with a simpler or more specific query is safe.","path":"/api/v3.0/candidate-search/public/search"}}}}}}},"tags":["Candidate Search API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/candidate-search/public/usage":{"get":{"operationId":"candidateSearchPublicUsage","summary":"Current daily quota usage for the calling organization.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key>. Does not consume daily quota. Throttled to 60 requests per minute per API key.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateSearchUsageDto"}}}},"400":{"description":"A malformed organizationId or workspaceId query parameter was supplied (not a 24-character hex ObjectId). details is an empty array for this case.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"examples":{"VALIDATION_ERROR":{"summary":"Malformed organizationId query parameter","value":{"statusCode":400,"errorCode":"VALIDATION_ERROR","message":"organizationId is invalid","path":"/api/v3.0/candidate-search/public/usage","details":[]}}}}}},"401":{"description":"Authentication failed: no API key was presented, or the presented key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}}},"examples":{"API_KEY_MISSING":{"summary":"No API key presented","value":{"statusCode":401,"errorCode":"API_KEY_MISSING","message":"Missing API key. Send it with x-api-key or Authorization: Bearer <key>.","path":"/api/v3.0/candidate-search/public/usage"}},"API_KEY_INVALID":{"summary":"Key not recognized","value":{"statusCode":401,"errorCode":"API_KEY_INVALID","message":"API key is invalid.","path":"/api/v3.0/candidate-search/public/usage"}},"API_KEY_EXPIRED":{"summary":"Key past its expiry","value":{"statusCode":401,"errorCode":"API_KEY_EXPIRED","message":"API key has expired.","path":"/api/v3.0/candidate-search/public/usage"}},"API_KEY_REVOKED":{"summary":"Key revoked","value":{"statusCode":401,"errorCode":"API_KEY_REVOKED","message":"API key has been revoked.","path":"/api/v3.0/candidate-search/public/usage"}}}}}},"403":{"description":"The key authenticated but is not allowed to run this request: the organization lacks a qualifying paid plan, the key is missing the candidate-search:read scope, or it cannot access the resolved organization or workspace.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}}},"examples":{"PLAN_REQUIRED":{"summary":"Organization is not on a qualifying paid plan","value":{"statusCode":403,"errorCode":"PLAN_REQUIRED","message":"Candidate Search API access requires a Platinum, Diamond, or Enterprise plan.","path":"/api/v3.0/candidate-search/public/usage"}},"SCOPE_FORBIDDEN":{"summary":"Key lacks the candidate-search:read scope","value":{"statusCode":403,"errorCode":"SCOPE_FORBIDDEN","message":"API key scope is not allowed","path":"/api/v3.0/candidate-search/public/usage"}},"ORG_ACCESS_DENIED":{"summary":"Key cannot access the resolved organization","value":{"statusCode":403,"errorCode":"ORG_ACCESS_DENIED","message":"API key cannot access this organization","path":"/api/v3.0/candidate-search/public/usage"}},"WORKSPACE_ACCESS_DENIED":{"summary":"Key cannot access the resolved workspace","value":{"statusCode":403,"errorCode":"WORKSPACE_ACCESS_DENIED","message":"API key cannot access this workspace","path":"/api/v3.0/candidate-search/public/usage"}}}}}},"429":{"description":"The usage endpoint is throttled to 60 requests per minute per API key. retryAfter is the whole number of seconds until the next minute.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"object","required":["limit","period"],"properties":{"limit":{"type":"integer"},"period":{"type":"string","enum":["minute"]}}},"retryAfter":{"type":"integer","description":"Whole seconds to wait before retrying."}}},"examples":{"RATE_LIMIT_EXCEEDED":{"summary":"More than 60 usage checks in a minute","value":{"statusCode":429,"errorCode":"RATE_LIMIT_EXCEEDED","message":"Too many usage checks. This endpoint allows 60 requests per minute per API key.","path":"/api/v3.0/candidate-search/public/usage","retryAfter":30,"details":{"limit":60,"period":"minute"}}}}}}},"500":{"description":"An unexpected error occurred while reading usage (e.g. the quota store was unreachable). The underlying cause is intentionally hidden from the response body.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","errorCode","message","path"],"properties":{"statusCode":{"type":"integer"},"errorCode":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}}},"examples":{"CANDIDATE_SEARCH_API_ERROR":{"summary":"Unexpected server error","value":{"statusCode":500,"errorCode":"CANDIDATE_SEARCH_API_ERROR","message":"Candidate Search API request failed.","path":"/api/v3.0/candidate-search/public/usage"}}}}}}},"tags":["Candidate Search API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}}},"components":{"schemas":{"CandidateSearchRequestDto":{"type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":300,"description":"Natural-language candidate search, e.g. 'bilingual customer support agent in Mexico City'."},"location":{"type":"string","maxLength":120,"description":"Optional location filter (free text city/region/country), e.g. 'Bogota, Colombia'."},"remote":{"type":"boolean","description":"When true, bias/limit results to remote-capable candidates."},"requireVideo":{"type":"boolean","description":"When true, only return candidates with a playable video profile."},"language":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Preferred resume language code (for example en or es). Results are biased toward this language; best-effort, not a strict filter.","example":"en"},"createdAfter":{"type":"string","description":"ISO 8601 date-time. Only return candidates whose searchable content was updated after this instant.","example":"2026-06-01T00:00:00.000Z"},"page":{"type":"number","minimum":1,"maximum":100,"default":1,"description":"1-based page number (max 100)."},"pageSize":{"type":"number","minimum":1,"maximum":25,"default":10,"description":"Results per page (max 25)."}},"required":["query"]},"CandidateSearchResponseDto":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/CandidateSearchResultDto"}},"hasMore":{"type":"boolean","description":"Whether another page exists. This API paginates on hasMore only - no total count is available."},"page":{"type":"number","description":"Echoed 1-based page number."},"pageSize":{"type":"number","description":"Echoed page size."}},"required":["results","hasMore","page","pageSize"]},"CandidateSearchUsageDto":{"type":"object","properties":{"dailyQuota":{"type":"number","description":"Maximum successful candidate-search API calls allowed per organization per UTC day.","example":100},"used":{"type":"number","description":"Quota-consuming candidate-search calls made with this organization's API keys today (UTC).","example":12},"remaining":{"type":"number","description":"Calls still available today: max(0, dailyQuota - used).","example":88},"resetsAt":{"type":"string","description":"ISO-8601 timestamp of the next UTC midnight, when used resets to 0.","example":"2026-07-08T00:00:00.000Z"},"period":{"type":"string","description":"Quota window. Always utc_day in v1.","enum":["utc_day"],"example":"utc_day"}},"required":["dailyQuota","used","remaining","resetsAt","period"]},"CandidateSearchResultDto":{"type":"object","properties":{"candidateId":{"type":"string","description":"Opaque, encrypted candidate identifier (pc1....). Use it to reach the candidate through the CazVid app; it is not a raw platform id.","example":"pc1.aGVsbG8td29ybGQ"},"displayName":{"type":"string","nullable":true,"description":"Candidate display name (contact info scrubbed)."},"headline":{"type":"string","nullable":true,"description":"Resolved current/most-recent job title."},"summary":{"type":"string","nullable":true,"description":"Short experience summary (contact info scrubbed)."},"topSkills":{"description":"Top skills (contact info scrubbed).","type":"array","items":{"type":"string"}},"matchedSkills":{"description":"Subset of top skills that matched the query.","type":"array","items":{"type":"string"}},"matchTier":{"type":"string","nullable":true,"description":"Relative match tier for the query, when available."},"locationName":{"type":"string","nullable":true},"countryCode":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2 country code, when available."},"isRemote":{"type":"boolean","description":"Whether the candidate is remote-capable."},"language":{"type":"string","nullable":true,"description":"ISO 639-1 resume language, when available."},"hasVideo":{"type":"boolean","description":"Whether a playable video profile exists."},"videoUrl":{"type":"string","nullable":true,"description":"Video profile URL (CazVid-hosted), when available."},"thumbnailUrl":{"type":"string","nullable":true,"description":"Video thumbnail URL (CazVid-hosted), when available."},"avatarUrl":{"type":"string","nullable":true,"description":"Avatar image URL (CazVid-hosted), when available."},"cazumeUrl":{"type":"string","nullable":true,"description":"Public Cazume profile URL, present only when the candidate has published one."},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of the candidate's most recent searchable content."}},"required":["candidateId","topSkills","matchedSkills","isRemote","hasVideo"]}},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"bearer":{"type":"http","scheme":"bearer"}}}}