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, links quotes, records qualification evidence, and moves deals to won or lost.

Create with a next action

POST /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. When the action is done, POST /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"
  }'

Quotes, evidence, and outcomes

Attach a same-client quote with POST /opportunities/{id}/quotes/{quoteId}/link and detach it with /unlink, which also recomputes the opportunity value. Qualification checkpoints are recorded at POST /opportunities/{id}/evidence; the log is append-only, so fixes go through /evidence/{evidenceId}/correct with an audit note. Close a deal with POST /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 /opportunities/{id}/timeline.

Suggestions and the work queue

AlgaPSA generates opportunity suggestions from tenant activity. List them with GET /opportunities/suggestions, then /accept one to create a prefilled opportunity, /dismiss it for good, or /snooze it until a future date. GET /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.