Pagination & filtering

Pagination

Collection endpoints accept:

Paginated responses use the canonical { data, meta: { pagination } } envelope. Use the pagination metadata rather than inferring the last page from its item count.

Candidate filters

GET /candidates supports:

Candidate stages and applications

GET /jobs/{jobId}/candidate-stages returns the configured hiring pipeline for a job. Use the stage code to interpret per-job candidate status values. A negative stage code represents a rejection stage. These negative codes can appear in responses, but the current GET /candidates status filter rejects negative values with 400.

GET /candidates/{candidateId}/applications returns the jobs associated with a candidate and the candidate's current stage in each job. appliedAt is the earliest known association with the job. updatedAt reflects the stored candidate/profile and job-association timestamps; it is not a complete timestamp for every hiring-stage change.

Example: candidates updated for a job

curl --get 'https://api.cvviz.com/v1/candidates' \
 --header 'Authorization: Bearer YOUR_API_SECRET' \
 --data-urlencode 'page=1' \
 --data-urlencode 'pageSize=10' \
 --data-urlencode 'job_id=901' \
 --data-urlencode 'updated_since=2026-09-01T00:00:00Z'

Replace 901 with your job ID. Add only filters documented by that endpoint; do not assume a filter supported by candidates is also supported by jobs.

Dates and units

Use RFC 3339 timestamps with a timezone, for example 2026-09-01T00:00:00Z. Job experience bounds are in years; candidate experienceMonths is in months. Read field descriptions before comparing values across resources.

Synchronization limits

Page-based results can change while you read them. Deduplicate by resource ID. Candidate updated_since filters profile updates; it is not a complete event feed for every related note, application or deletion. Do not assume snapshot pagination or deletion notifications that the reference does not promise.