Find candidates and download resumes

A candidate is a person in your database. An application connects that person to a particular job and its hiring stage. One candidate can have multiple applications.

Find the candidate

Use GET /candidates with candidates.read. To narrow results to a job, use job_id; a stage status filter requires job_id. Discover stage codes with GET /jobs/{jobId}/candidate-stages (candidates.read). The status query filter accepts non-negative integers only. Negative rejection-stage codes can appear in pipeline and application data, but passing one to this filter returns 400. See Pagination & filtering.

Retrieve a profile with GET /candidates/{candidateId}. Read job associations with GET /candidates/{candidateId}/applications, which also requires candidates.read. Do not confuse a candidate's application stage with a job's lifecycle status.

Access a candidate's resume

GET /candidates/{candidateId} includes the original resume metadata:

{
 "data": {
 "id": 501,
 "resume": {
 "fileName": "Asha_Sharma_Resume.pdf",
 "downloadUrl": "https://api.cvviz.com/v1/candidates/501/resume/download"
 }
 }
}

This is a partial response example. resume is null when valid original-resume metadata is unavailable. Candidate responses also include current company and job title, phone country code, LinkedIn/GitHub links and notice period where known.

Call downloadUrl with your API credential, which must have resumes.download. The API checks access and redirects (302) to a five-minute file URL. Follow the redirect without forwarding the API Authorization header to the file host. The API link requires authentication; it is not a public link for embedding in a web page.

For an integration that needs a direct file URL, request GET /candidates/{candidateId}?include=resume_download_url with both candidates.read and resumes.download. The resume object then also contains directDownloadUrl and expiresAt. Never log or persist the temporary URL. Anyone possessing it can download the file until it expires, even if the credential is revoked in the meantime. Obtain a fresh URL when needed.

Candidate profile reads, candidate application history and resume access all respect the account's content-access policy. When storage-capacity restrictions are enforced, these requests can return 402. API request capacity does not bypass candidate or resume-content restrictions.