RErecruitwithatlas
Fees

List fees

Changed on

Use this endpoint to retrieve a paginated list of fees for the authenticated agency.

A fee represents a financial charge tied to a project — typically a placement fee earned when a candidate is successfully hired. Each fee tracks the amount, currency, status, and payment details, and may include one or more splits showing how the revenue is distributed among fee earners.

What you can filter by:

  • projectIds — comma-separated project UUIDs to limit fees to specific projects
  • createdAfter / createdBefore — only return fees created within a specific ISO 8601 date range
  • updatedAfter / updatedBefore — only return fees last modified within a specific ISO 8601 date range. 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 & ordering: Results are returned in pages, ordered by creation date. Pass order=asc for oldest first, or order=desc (default) for newest first. Use the page and pageSize parameters to move through large result sets. The response includes a top-level total so you know how many results exist in total.

Deletions (tombstones): Soft-deleted fees are excluded by default. Pass includeDeleted=true to also receive deleted fees 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. A deleted fee tombstone also returns the splits it had at deletion time, each carrying its own deletedAt; live fees only ever return their live splits.

What you get back: An array of fee objects, each with its full set of fee splits and earner identity inlined.

get/api/v1/fees

Request

Query parameters

projectIdsstring

Comma-separated project UUIDs to filter fees by

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 fees as tombstones (with a populated deletedAt). Defaults to false. Pair with updatedAfter to incrementally sync deletions.

Example:false
pageinteger

Page number (1-indexed)

Example:1
pageSizeinteger

Items per page (max 100)

Example:25
order'asc' | 'desc'

Sort order by creation date — desc (newest first, default) or asc (oldest first)

Example:desc

Response

Paginated list of fees

status'ok' required

Example response

{
  "data": [
    {
      "feeType": {
        "name": "Placement Fee"
      },
      "feeDate": "2025-06-15",
      "amount": "15000.00",
      "defaultAmount": "15000.00",
      "currency": "GBP",
      "defaultCurrency": "GBP",
      "projectFeeStatus": "earned",
      "splits": [
        {
          "feeEarner": {
            "name": "Jane Smith",
            "email": "jane@agency.com"
          },
          "feeType": {
            "name": "Placement Fee"
          },
          "share": "60.00"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "total": 42,
    "hasMore": true
  }
}

Changes