RErecruitwithatlas
Prospects

List prospects

Changed on

Returns a paginated, agency-scoped list of prospects — people attached to opportunities (opportunity_people rows) — as a flat list, not nested under a single opportunity.

Relationship to the Spec CV / float workflow. A prospect is created whenever a person is attached to an opportunity. The Spec CV workflow (speculatively sending a candidate CV to a client with no active role) creates a speculative opportunity plus a prospect on float/send, so filtering with opportunityType=speculative surfaces spec-CV prospects, while opportunityType=regular returns prospects on standard business-development opportunities.

Filters:

  • opportunityType — regular | speculative (the parent opportunity type)
  • opportunityId — restrict to a single opportunity
  • createdAfter / createdBefore — filter on when the prospect was added (ISO 8601 or YYYY-MM-DD)
  • updatedAfter / updatedBefore — filter on when the prospect was last modified (ISO 8601 or YYYY-MM-DD). Use updatedAfter as an incremental-sync cursor: persist the max updatedAt you receive and pass it back on the next poll to fetch only what changed (upsert by id).
  • includeDeleted — when true, soft-deleted prospects are included as tombstones (with a populated deletedAt). Pair with updatedAfter to incrementally sync deletions: a soft-delete bumps updatedAt, so the removed prospect resurfaces on the next poll with deletedAt set.

addedBy is populated from the prospect creator where recorded; it is null for legacy rows that predate creator attribution.

get/api/v1/prospects

Request

Query parameters

opportunityType'regular' | 'speculative' | 'job' | 'generic'

Filter by the type of the parent opportunity. speculative opportunities are created by the Spec CV / float workflow (sending a candidate CV to a client with no active role); regular opportunities are standard business-development opportunities.

Example:regular
opportunityIdstring uuid

Only return prospects belonging to this opportunity

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 prospects 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
perPageinteger

Alias for pageSize

Response

List of prospects

status'ok' 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 opportunityType

    • info

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

    • info

      added the optional property to the response with the status

    • info

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

    • info

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