Candidates

Get a candidate

Retrieve a candidate profile, including original resume metadata when available.

GET

/candidates/{candidateId}

Get a candidate

curl --request GET \
  --url 'https://api.cvviz.com/v1/candidates/{candidateId}?include=resume_download_url' \
  --header 'Authorization: Bearer <token>'

{
  "data": {
    "createdAt": "2026-08-20T08:15:00.000Z",
    "currentCompany": "Example Company",
    "currentJobTitle": "Backend Engineer",
    "currentLocation": {
      "city": "Pune",
      "country": "India",
      "state": "Maharashtra"
    },
    "email": "asha.sharma@example.com",
    "experienceMonths": 48,
    "firstName": "Asha",
    "id": 501,
    "jobContext": null,
    "lastName": "Sharma",
    "noticePeriod": {
      "unit": "M",
      "value": 1
    },
    "originalJobId": 901,
    "phone": "+919876543210",
    "phoneCountryCode": "91",
    "professionalProfiles": {
      "github": null,
      "linkedin": null
    },
    "qualifications": [
      "Bachelor's degree"
    ],
    "resume": {
      "downloadUrl": "https://api.cvviz.com/v1/candidates/501/resume/download",
      "fileName": "Asha_Sharma_Resume.pdf"
    },
    "skills": [
      "TypeScript",
      "Node.js",
      "MySQL"
    ],
    "source": "Career page",
    "updatedAt": "2026-08-30T15:20:00.000Z"
  }
}

Resume access

The resume object includes the original filename and an authenticated download link.
Downloading the file requires the additional resumes.download scope.
Add include=resume_download_url to request a direct file URL valid for five minutes. This also requires resumes.download.

Treat direct file URLs as temporary secrets. Do not log, persist or publicly share them.

See Find candidates and download resumes for the download flow.

Permissions

candidates.read

Authorizations

Authorizationstringheaderrequired

Use Authorization: Bearer <api-credential>.

Path Parameters

candidateIdnumberrequired

CVViZ candidate identifier.

Example: 501

Query Parameters

includeenum<string>query

Include a five-minute direct resume URL. Requires resumes.download in addition to candidates.read. Treat the URL as a temporary secret; do not log or persist it.

Available options: resume_download_url

Response

Successful response.

X-API-Daily-Limitintegerheader

Daily account request allowance, when metered. Shared across API credentials.

Required range: 0 <= x

X-API-Daily-Remainingintegerheader

Requests remaining in the daily window after admission.

Required range: 0 <= x

X-API-Daily-Resetstringheader

Daily window reset time in UTC.

X-API-Monthly-Limitintegerheader

Monthly account request allowance, when metered. Shared across API credentials.

Required range: 0 <= x

X-API-Monthly-Remainingintegerheader

Requests remaining in the monthly window after admission.

Required range: 0 <= x

X-API-Monthly-Resetstringheader

Monthly window reset time in UTC.

X-Request-IDstringheader

Request correlation identifier. Supply this value when contacting support.

Example: 01J7Y8N9P0Q1R2S3T4U5V6W7X8

X-API-Contractstringheader

Response envelope contract version.

Example: canonical-v1

RateLimit-Limitintegerheader

Account request limit for capacity add-ons; effective credential request-unit limit for included legacy access.

Example: 600

RateLimit-Remainingintegerheader

Requests remaining for capacity add-ons, or request units for included legacy access.

Example: 598

RateLimit-Resetintegerheader

Seconds until the current minute window resets.

Example: 30

dataobjectrequired

Show child attributes

Still need help? Ask the team