RErecruitwithatlas
Opportunities

Create an opportunity

Changed on

Creates a new opportunity with optional relations (prospects, companies, job leads). When candidateId is provided the opportunity type is set to speculative; otherwise it is regular. The first pipeline stage is assigned automatically. When no name is provided and the opportunity has more than one prospect or any target company / job lead, a title is generated by the AI title service; otherwise a deterministic default name is used. AI title generation failures are logged and the deterministic name is kept — the create still succeeds.

Target companies. The opportunity's target companies are the union of the explicit companyIds you pass and the current company resolved for each prospect (resolved in order: an explicit per-person company, then the prospect's headlineCompanyId, then their existing company-contact link). Companies are deduplicated by ID, so a prospect whose company is already in companyIds does not produce a second entry. Because prospect companies are resolved by ID, linking your contacts to a real company up front (via headline.companyId on POST /api/v1/people) is what keeps duplicate stub companies off the opportunity. Every resolved company must belong to your agency or the request fails.

post/api/v1/opportunities

Request

Request body

namestring nullable

Opportunity name (max 500 chars)

notesstring nullable

Free-text notes (max 10 000 chars). Stored on the opportunity itself and returned as the top-level notes string on GET — not as an entry in the opportunityNotes array, which holds individual note records added by users in Atlas.

aiSummarystring nullable

AI-generated summary for the opportunity (max 10 000 chars)

valueinteger nullable

Monetary value (integer, 0–1 000 000 000)

ownerIdstring uuid nullable

Owner user ID (defaults to authenticated user)

candidateIdstring uuid nullable

Person being specced out. Sets type to speculative

prospectIdsstring[] nullable

Person IDs to attach as prospects (max 50) — the id from GET /api/v1/people. NOT CompanyContact junction IDs (companyContact.id) and NOT the prospects[].id rows returned by opportunity endpoints. Merged IDs are resolved to their canonical person automatically.

companyIdsstring[] nullable

Target companies (max 50)

jobLeadIdsstring[] nullable

Projects to link as job leads (max 50)

Example request

{
  "name": "Acme Corp — Senior Engineer",
  "notes": "Warm intro via LinkedIn",
  "aiSummary": "High-fit candidate based on past placements.",
  "value": 25000,
  "ownerId": "550e8400-e29b-41d4-a716-446655440001",
  "candidateId": "550e8400-e29b-41d4-a716-446655440005"
}

Response

Opportunity created

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 optional property to the response with the status

    • info

      added the required property / to the response with the status