Candidates

List candidates

List candidate profiles in your CVViZ account.

GET

/candidates

List candidates

curl --request GET \
  --url 'https://api.cvviz.com/v1/candidates?page=1&pageSize=10&job_id=901&status=3&updated_since=2026-08-31T00%3A00%3A00Z' \
  --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": {
        "jobId": 901,
        "status": 3
      },
      "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"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "totalItems": 1,
      "totalPages": 1
    }
  }
}

Filters

job_id: limit results to candidates associated with one job.
status: filter by that job's candidate stage. Requires job_id.
updated_since: filter by the candidate profile's update time.

Stage codes come from GET /jobs/{jobId}/candidate-stages; they are not job lifecycle codes.

Permissions

candidates.read

Pagination

Use page and pageSize; see the query parameters below for defaults and limits. See Pagination & filtering for examples.

Authorizations

Authorizationstringheaderrequired

Use Authorization: Bearer <api-credential>.

Query Parameters

pageintegerquerydefault:1

One-based page number.

Required range: 1 <= x

Example: 1

pageSizeintegerquerydefault:10

Number of records returned per page.

Required range: 1 <= x <= 100

Example: 10

job_idintegerquery

Restrict candidates to a job in the credential's CVViZ account. Required when status is supplied.

Required range: 1 <= x

Example: 901

statusintegerquery

Restrict candidates to this job workflow status. This filter requires job_id.

Required range: 0 <= x

Example: 3

updated_sincestringquery

Return candidate profiles updated at or after this RFC 3339 timestamp. A timezone is required.

Example: 2026-08-31T00:00:00Z

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

dataobject[]required

Show child attributes

metaobjectrequired

Show child attributes

Still need help? Ask the team