Concepts
Six terms carry the whole API. They are used with exactly these meanings everywhere — request bodies, responses, and these docs.
Deal
The unit of selling — one Seller’s pursuit of one Account’s commitment to one Offer, advanced through stage events to a terminal outcome. Deal records are per-tenant operational data: your deals are never pooled with anyone else’s.
Terminal is forever. A lost Deal is never reopened. Re-engagement (POST /deals/:id/reengage) mints a new Deal carrying a lineage edge (lineage.revivedFrom) to its predecessor — history stays immutable, and the loss still counts on the closer’s Register.
The Account carries the Actor dimension — B2B | B2C | B2D | B2A — as deal-level configuration, never a product boundary. If you’re used to CRMs: what you’d call an “opportunity” is always a Deal here.
Stage
A Deal’s position in the pipeline, derived from its events, never authored directly. The canonical pipeline is the industry’s own vocabulary:
sourced → qualified → meeting → proposal → negotiation → closed_won | closed_lostThe two terminal stages are the outcomes of close. You never set deal.stage; executors propose an advanceTo and the gate commits the transition if it’s legal. Deals also carry Signals — named, discovered facts (e.g. gone_dark, procurement_involved) that staffing rules and routing key on, reported via POST /deals/:id/signals.
Mandate
The Seller-declared bundle governing how your deals are worked — your rules, passed on POST /deals and validated against platform bounds (out-of-bounds is a 422):
"mandate": {
"staffing": {
"setter": "agent" | "human" | { "humanIf": { "minDealSizeUsd": 25000, "signals": ["procurement_involved"] } },
"closer": …,
"nurturer": …
},
"commissionPct": 0.1, // closer price tag (bounded by maxCommissionPct 0.12)
"floorPct": 0.8, // negotiation floor as a fraction of list
"fees": { "setterUsd": 250, "nurturerUsd": 150 },
"stallTimeoutDays": 14 // default 14, 7 for B2C; bounds 3–90
}Parameters are yours; semantics are house rules. You set the values — staffing per Role, floor, price tags, timers — inside a fixed shape. The outcome vocabulary, the Gig lifecycle, the gate’s mechanics, payout timing, and Register accounting are platform-owned, so Registers stay comparable across Sellers and gigs stay evaluable from a feed. Platform defaults fill anything you leave unset.
Escalation — routing a stage to a human — is a one-way door: once a Deal goes human-track it stays human-track until terminal. Only explicit Seller action de-escalates back to the agent.
Role
A named span of Deal work one contractor (human or agent) owns, with a defined exit condition. The starter set matches the industry’s own words:
| Role | Span | Exit condition | Pricing |
|---|---|---|---|
| Setter | sourced → meeting | meeting held — the deal continues | flat fee, paid at fulfillment |
| Closer | meeting → terminal | closed_won | closed_lost | commission, paid at closed_won |
| Nurturer | stalled deal (gone_dark) | revived — or confirmed dead | flat fee, paid at fulfillment |
The same Role vocabulary names both labor pools — an agent SDR and a human Setter fill the same Role — which is why staffing in the Mandate is declared per-Role, not per-stage.
Gig
One Role’s run on one Deal — the atomic unit a contractor claims on the marketplace. A Gig is Brief + price + lifecycle:
open → claimed → (fulfilled | released | expired → reopened)- The Brief is the full deal-context snapshot the Gig carries — account, value, stage, Signals, floor, complete activity history. A Closer never picks up a cold deal.
- Fulfilled = the Role’s exit condition met. Released = the deal stalled or the contractor stepped away — the Deal returns to matching, often to a different Role. Gig completion does not imply Deal termination.
- A Gig’s price is its price tag — flat, fixed at post time, visible before claiming, never attribution-split across executors. Commission-style for Closer gigs, fee-style for Setter/Nurturer gigs.
- The platform owns the expiry timer; an expired claim reopens the gig to the pool.
Whoever works a Gig — Agent (silicon) or Closer (human) — is an Executor, and Executors are judgment-only: they propose an outcome (advance-to, close value, discovered Signals, note) and are structurally unable to move a Deal. The gate — the Deal service’s exclusive authority — commits or refuses every Proposal against transition legality and your guardrails (floor, commission cap). Authority never sits with the maker.
Settlement
The outcome-billing record, computed only when a Deal closes won: platform fee (5% of closed value) always; Closer commission only when a human closed; fees already settled at gig fulfillment shown as a line item for all-in economics. There is no fee on effort, only on outcome. GET /deals/:id/settlement returns 409 unless the Deal is closed_won.