RErecruitwithatlas
People

List people

Changed on

Use this endpoint to retrieve a paginated list of people (contacts and candidates) across your entire agency.

It is the counterpart to Get a person (GET /api/v1/people/{id}) for bulk reads: sync every person into an external system, or count how many people each consultant added to the CRM over a period.

What you can filter by:

  • createdByIds — comma-separated Atlas user UUIDs; return only people added by those consultants (matches Person.createdById). This is the filter to use for "people/candidates added per consultant".
  • createdAfter / createdBefore — only people added within a date range (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value.
  • updatedAfter / updatedBefore — only people last modified within a date range (inclusive). Use updatedAfter as an incremental-sync cursor.
  • includeDeleted — when true, soft-deleted people are included as tombstones (with a populated deletedAt) so you can sync deletions. People merged into another person are tombstones too: a merged tombstone has mergedToId set to the ID of the person it was merged into, and a deleted one has mergedToId: null. The surviving person of a merge is a new record, so it appears as a live person with its own createdAt.

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

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 person includes id, firstName, lastName, headline (headlineRole, headlineCompanyName), relationshipType (contact vs candidate), the company they are a contact at (when applicable), the createdBy consultant, createdAt / updatedAt / deletedAt timestamps, and mergedToId (set only on merged tombstones). Use id with Get a person to fetch full details.

get/api/v1/people

Request

Query parameters

createdByIdsstring

Filter to people created by these Atlas users (the consultant who added them). Comma-separated user UUIDs — matches Person.createdById. Omit to return people added by anyone.

Example:550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001
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 people as tombstones (with a populated deletedAt). Defaults to false. Pair with updatedAfter to incrementally sync deletions.

Example:false
sortDirection'asc' | 'desc'

Sort direction by creation date (createdAt, then id as a tiebreaker). 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 people

status'ok' required

Example response

{
  "data": [
    {
      "headlineRole": "Regional Manager",
      "headlineCompanyName": "Dunder Mifflin",
      "relationshipType": "candidate"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "total": 42,
    "totalPages": 2
  }
}

Changes