Opportunities API

An opportunity is a potential deal with a client, and it always carries a next action so it cannot silently stall. This API creates and updates opportunities, moves deals between pipeline stages, links quotes, records qualification evidence, and marks deals won or lost.

Create with a next action

POST /api/v1/opportunities requires client_id, title, opportunity_type, currency_code, and a next_action with next_action_due. Deal value is split into mrr_cents, nrr_cents, and hardware_cents. The expected_close_date field is returned as a YYYY-MM-DD date string (not an ISO timestamp). When the action is done, POST /api/v1/opportunities/{id}/complete-action records it as an interaction and installs the replacement action in the same call.

curl https://algapsa.com/api/v1/opportunities \
  -H "X-API-Key: $ALGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "0197c1a2-...",
    "title": "Backup refresh for all three sites",
    "opportunity_type": "expansion",
    "currency_code": "USD",
    "mrr_cents": 42000,
    "next_action": "Send backup sizing questionnaire",
    "next_action_due": "2026-08-03T17:00:00Z"
  }'

Update an opportunity

PUT /api/v1/opportunities/{id} replaces the full writable body. PATCH /api/v1/opportunities/{id} is an alias that accepts a partial body — include only the fields you want to change, and omitted fields are left untouched. Both verbs go through the same validation.

For opportunities managed by a pipeline automation flow, pipeline_id, stage_id, and probability are flow-owned. Supplying any of these on a PUT or PATCH for a flow-managed opportunity returns 422 Unprocessable Entity. Use POST /stage to advance a flow-managed deal between stages instead.

Move to a different pipeline stage

POST /api/v1/opportunities/{id}/stage transitions an open deal to a different stage in the same pipeline without closing it. Supply the target stage_id in the body. This is the correct endpoint for both pipeline automation flows and manual stage moves; supplying stage_id directly on PUT/PATCH is rejected for flow-managed opportunities.

curl -X POST https://algapsa.com/api/v1/opportunities/0197c1a2-.../stage \
  -H "X-API-Key: $ALGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "0197c1b3-..."
  }'

Quotes, evidence, and outcomes

Attach a same-client quote with POST /api/v1/opportunities/{id}/quotes/{quoteId}/link and detach it with /unlink, which also recomputes the opportunity value. Qualification checkpoints are recorded at POST /api/v1/opportunities/{id}/evidence; the log is append-only, so fixes go through /api/v1/opportunities/{id}/evidence/{evidenceId}/correct with an audit note. Close a deal with POST /api/v1/opportunities/{id}/win, which can convert an accepted linked quote into a draft agreement, or /lose with a required loss reason. The full history of linked interactions is at GET /api/v1/opportunities/{id}/timeline.

Suggestions and the work queue

AlgaPSA generates opportunity suggestions from tenant activity. List them with GET /api/v1/opportunities/suggestions, then /accept one to create a prefilled opportunity, /dismiss it for good, or /snooze it until a future date. GET /api/v1/opportunities/work-queue returns the composed queue of deals needing attention for the authenticated user, the same view the app shows.

Endpoints

Every endpoint links through to its full parameters, request and response schemas, and code samples.