List placements

Use this endpoint to retrieve a paginated list of placements (also called hires) within your agency, including their fees.

In Atlas, a placement represents a candidate that has been successfully placed into a role at a client company. This endpoint returns placements scoped to your agency, ordered by creation date.

What you can filter by:

• type - the placement type. Options are: permanent (a permanent hire with salary information) or contract (a contract role).
• createdAfter / createdBefore - only return placements created within a specific date range
• updatedAfter / updatedBefore - only return placements last modified within a specific date range (ISO 8601). Filters on the updatedAt field

Incremental sync: To keep an external copy in sync, use updatedAfter as a cursor: on each run, request updatedAfter=<the highest updatedAt you have seen so far>, page through the results, and persist the maximum updatedAt across the rows you receive. Pass that stored value as updatedAfter on the next run to fetch only records that changed since. Because the bound is inclusive you may re-receive the boundary row — upsert by id to stay idempotent.

Pagination: Results are returned in pages. Use the page and pageSize parameters to move through large result sets. The response includes a pagination object with page, pageSize, total, and totalPages.

What you get back: Each placement in the list includes its core fields, the top-level owner (the consultant the placement is attributed to — this maps to the candidate owner and is the primary field for counting placements per recruiter, with id, name, and email), the related project and candidate IDs, and an array of fees linked to it. Each fee includes its amount in both the original currency and the agency currency. Fee earners on fees[].splits[] are finance/commission attribution only — do not use them for placement counts.

Approval: Each placement carries approvalStatus: pending (approval required, not yet given), approved (approval required and given), or null (the placement does not need approval). Pending placements are included in the list — to count only placements that are final, keep rows whose approvalStatus is approved or null.

Deletions (tombstones): Soft-deleted placements are excluded by default. Pass includeDeleted=true to also receive deleted placements as tombstones — each carries a populated deletedAt (live rows have deletedAt: null). Combine includeDeleted=true with updatedAfter to incrementally pick up deletions: a soft-delete bumps updatedAt, so the deleted row resurfaces in the next poll with deletedAt set.