---
title: "List candidates"
method: GET
path: "/candidates"
tags: ["Candidates"]
---

# List candidates

`GET /candidates`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/candidates`
- Auth: HTTP bearer

Returns the candidates (board users with role `candidate`) of the authenticated account. Per-candidate saved-job and alert counts are not inlined here. Fetch them via `GET /v1/candidates/{id}`. Requires `candidates.read`.

## Query parameters

- `cursor` string: Pagination cursor.
- `limit` integer: Page size (1–100, default 50).
- `search` string: Case-insensitive substring match on the candidate email or display name.
- `handle` string: Exact public-profile handle lookup.
- `hasResume` 'true' | 'false': Filter by whether the candidate has uploaded a resume.
- `createdFrom` string, date-time: ISO-8601 lower bound (inclusive) on registration date.
- `createdTo` string, date-time: ISO-8601 upper bound (inclusive) on registration date.

## Response `200`

Successful response.

- object
  - `object` 'list', required
  - `url` string, required
  - `hasMore` boolean, required
  - `nextCursor` string, nullable, required
  - `data` Candidate[], required
    - `id` string, required: Unique identifier for the candidate.
    - `object` 'candidate', required: String representing the object's type.
    - `email` string, required: The candidate's email address.
    - `displayName` string, nullable, required: The candidate's display name.
    - `handle` string, nullable, required: Public-profile handle, or `null`.
    - `avatarUrl` string, nullable, required: Avatar URL, or `null`.
    - `hasResume` boolean, required: Whether a resume is on file. On list rows this reflects the stored pointer; on the single-candidate detail it reflects the resolved blob (always agrees with `resume !== null`), so the two can briefly disagree if a stored file was garbage-collected.
    - `createdAt` string, required: ISO-8601 timestamp of when the candidate registered.
    - `candidateCreatedAt` string, required: ISO-8601 timestamp when this Board user became an operator-visible Candidate. This is the reconciliation counterpart of candidate.created, not newsletter permission.
    - `updatedAt` string, nullable, required: ISO-8601 timestamp of the latest approved Candidate identity update, or null for older rows.
    - `revision` integer, required: Monotonic Candidate lifecycle revision; legacy rows are 0 until the rollout migration runs.
    - `lastActiveAt` string, nullable, required: ISO-8601 timestamp of the last activity on the board (a sign-in or signed-in use), to the hour, or `null`.

## Other responses

- `default`: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.

## Changes

- **2026-10-19** `c34152c38176`: 1 info
  - added the optional property `error/upgrade` to the response with the `default` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/candidates/get.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)