List candidates in a project

Use this endpoint to retrieve a paginated list of candidates enrolled in a specific project, including both active and rejected candidates by default.

In Atlas, a candidate represents a person who has been added to a project's recruitment pipeline. Each candidate sits at a specific status within a specific stage of the pipeline (e.g. Sourcing → Added, Shortlist → Reviewed). This endpoint lets you read the current state of every candidate in a project, with the same ordering and filtering used by the Atlas web app candidate list.

What you can filter by:

• phase — comma-separated pipeline phase names (internal_selection, presentation, first_round, late_stage)
• stageId — comma-separated CandidateStage UUIDs
• statusId — comma-separated CandidateStatus UUIDs
• excludeRejected — when true, rejected candidates (non-null rejectedAt) are omitted

Ordering: Results are sorted by pipeline position — first by stage position, then by status position. Use sortDirection=asc or sortDirection=desc (default desc) to control the order. This matches the in-app candidate list ordering.

Pagination: Use page (1-based) and pageSize (1–100, default 25). The response includes a pagination object with page, pageSize, total, and hasMore.

What you get back: Each candidate includes its ID, a nested person object (with id, name, headline, and avatarUrl — use person.id with the People endpoints to fetch the person's full details, history, etc.), the current pipeline phase/stage/status, rejection state (rejectedAt, rejectionType, rejectionReason, customRejectionReasonId, rejectionDetails, rejectedBy — where rejectionType says who rejected the candidate (by_us, by_client or self), rejectionReason is the label of the agency-defined reason when one was picked, falling back to the predefined reason code, and rejectedBy is the Atlas user who recorded the rejection), the recruiter's shortlist comment (comment as plain text, commentFormatted as HTML), and timestamps. Rejected candidates are not moved, so a rejected candidate's stage and status are the ones they were rejected at — combine rejectionType with stage to tell, for example, a client rejection from the longlist apart from one after interview. To find the available stage/status IDs for a project, call the Get project details endpoint first.

Deprecated fields: firstName, lastName, headlineRole, and headlineCompanyName are still returned at the top level for backwards compatibility but are deprecated — use the equivalent fields inside person instead.