Opportunities API

https://<your-host>/api/opportunities/

List

GET /api/opportunities/?stage=proposal&close_date__lte=2026-12-31
Authorization: Bearer <token>

{
  "count": 47,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "o001-…",
      "name": "Acme — Annual 2026",
      "account": { "id": "a001-…", "name": "Acme Corp" },
      "amount": "24000.00",
      "currency": "USD",
      "stage": "proposal",
      "probability": 60,
      "close_date": "2026-06-30",
      "owner": { "id": "u034-…", "email": "rep@yours.com" },
      "stakeholders": [
        { "id": "c012-…", "first_name": "Jane", "last_name": "Doe" }
      ],
      "custom_fields": { "competitor": "incumbent_vendor" },
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Filterable fields: stage, owner, account, close_date__gte, close_date__lte, amount__gte, tags, cf_<key>.

Create

POST /api/opportunities/
{
  "name": "Acme — Annual 2026",
  "account_id": "a001-…",
  "amount": "24000",
  "currency": "USD",
  "stage": "discovery",
  "close_date": "2026-06-30",
  "stakeholder_ids": ["c012-…"],
  "custom_fields": { "competitor": "incumbent_vendor" }
}

probability defaults from the stage if you omit it.

Detail

GET /api/opportunities/<id>/

Returns the opportunity plus activities, stakeholders (full contact records), and custom_field_definitions.

Update / delete

PATCH  /api/opportunities/<id>/
PUT    /api/opportunities/<id>/
DELETE /api/opportunities/<id>/

Stage transitions

POST /api/opportunities/<id>/transition/
{ "stage": "negotiation" }

Validates the transition against your org's pipeline policy. Moving to a won or lost stage requires:

• won: actual_amount and actual_close_date
• lost: lost_reason (free text or one of the configured reason codes)

Closing fires the opportunity.won or opportunity.lost webhook.

Forecast

GET /api/opportunities/forecast/?close_date__gte=2026-04-01&close_date__lte=2026-06-30

Returns weighted and unweighted totals grouped by month:

{
  "currency": "USD",
  "months": [
    { "month": "2026-04", "unweighted": 180000, "weighted": 92500 },
    { "month": "2026-05", "unweighted": 145000, "weighted": 76000 },
    { "month": "2026-06", "unweighted": 220000, "weighted": 154000 }
  ]
}