RErecruitwithatlas
Opportunities

List opportunities

Changed on

Returns a paginated list of opportunities with optional filtering.

Date filters:

  • createdAfter / createdBefore - only return opportunities created within a specific date range (ISO 8601)
  • updatedAfter / updatedBefore - only return opportunities 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.

Deletions (tombstones): Soft-deleted opportunities are excluded by default. Pass includeDeleted=true to also receive deleted opportunities 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.

get/api/v1/opportunities

Request

Query parameters

pageinteger

Page number (min: 1)

Example:1
pageSizeinteger

Items per page (min: 1, max: 100)

Example:25
archivedboolean

Show archived opportunities only. Applies to live rows; when includeDeleted=true, soft-deleted opportunities are always returned as tombstones regardless of their archived state.

namestring

Case-insensitive partial match on opportunity name

stageIdstring

Comma-separated pipeline stage ID(s)

ownerEmailstring

Comma-separated owner email(s)

type'regular' | 'speculative' | 'job' | 'generic'

Filter by opportunity type

Example:regular
status'open' | 'won' | 'lost'

Filter by opportunity status

Example:open
candidateIdstring uuid

Filter by associated candidate (person) ID

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

Example:false

Response

List of opportunities

status'ok' required
totalinteger required

Total number of opportunities matching the filter, across all pages

pageinteger required

1-based page index that produced this response

pageSizeinteger required

Maximum number of items per page (echoed back from the request)

hasMoreboolean required

Changes

  • cd4bc8bbd95eRevision changes
    • warning

      added the new generic enum value to the // response property for the response status

    • warning

      added the new job enum value to the // response property for the response status

    • info

      added the new enum value generic to the query request parameter type

    • info

      added the new enum value job to the query request parameter type

    • info

      added the optional property to the response with the status

    • info

      added the required property // to the response with the status