RErecruitwithatlas
Candidates

List candidates

Changed on

Use this endpoint to retrieve a paginated list of candidates across all projects in your agency.

In Atlas, a candidate represents a person who has been added to a project's recruitment pipeline. The same person can be a candidate on several projects at once, so each item in this list is one candidacy — a person at a specific status within a specific project's pipeline. Unlike List candidates in a project, this endpoint is not scoped to a single project, which makes it the right choice for syncing or reporting on candidates agency-wide.

What you can filter by:

  • personId — return every candidacy for a single person, across all of their projects
  • createdAfter / createdBefore — only candidacies added within a date range (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value
  • updatedAfter / updatedBefore — only candidacies last modified within a date range (inclusive). Use updatedAfter as an incremental-sync cursor: persist the largest updatedAt you receive and pass it back on the next run
  • includeDeleted — when true, soft-deleted candidacies are included as tombstones (with a populated deletedAt) so you can sync deletions

Ordering: Results are ordered by candidate creation date (createdAt, then id as a tiebreaker). Use sortDirection=asc or sortDirection=desc (default desc, newest first) to control the order.

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

What you get back: Each candidacy includes its ID, a nested person (id, name, headline, avatarUrl, and contact identities), the project it belongs to, the current pipeline stage and status, the owner, rejection state (null when active), and timestamps. Use person.id with the People endpoints to fetch a person's full details.

get/api/v1/candidates

Request

Query parameters

personIdstring uuid

Filter to candidacies for a single person (across every project they are a candidate in)

Example:550e8400-e29b-41d4-a716-446655440000
string
OR
string date-time
string
OR
string date-time
string
OR
string date-time
string
OR
string date-time
includeDeleted'true' | 'false'

Include soft-deleted candidates as tombstones (with a populated deletedAt). Defaults to false. Pair with updatedAfter to incrementally sync deletions.

Example:false
sortDirection'asc' | 'desc'

Sort direction by candidate creation date (createdAt, then id). Defaults to desc (newest first).

Example:desc
pageinteger

Page number (1-indexed)

Example:1
pageSizeinteger

Items per page (max 100)

Example:25
perPageinteger

Alias for pageSize

Response

Paginated list of candidates

status'ok' required

Example response

{
  "data": [
    {
      "person": {
        "avatarUrl": "https://berg-atlas-public.s3-eu-west-1.amazonaws.com/550e8400-e29b-41d4-a716-446655440000/7c9e6679-7425-40de-944b-e07fc1f90ae7/avatar/a1b2c3d4.jpeg"
      },
      "project": {
        "state": "active"
      },
      "stage": {
        "name": "Sourcing"
      },
      "status": {
        "name": "Added"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "total": 42,
    "totalPages": 2
  }
}

Changes