Candidates

List candidate events

Retrieve the candidate activity timeline.

GET

/candidates/{candidateId}/events

curl --request GET \
  --url 'https://api.cvviz.com/v1/candidates/{candidateId}/events?page=1&pageSize=10' \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "actorName": "Recruiter name",
      "description": "Moved to Interview",
      "id": "Status changed:2026-09-01T10:00:00.000Z:0",
      "jobId": 901,
      "jobTitle": "Senior Backend Engineer",
      "occurredAt": "2026-09-01T10:00:00.000Z",
      "type": "Status changed"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "totalItems": 1,
      "totalPages": 1
    }
  }
}

The timeline is capped at 1,000 events before pagination. Event IDs are derived from the timeline and should not be used as permanent synchronization keys.

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>.

Path Parameters

candidateIdnumberrequired

CVViZ candidate identifier.

Example: 501

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

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