Skip to main content
POST
/
deals
/
events
Ingest a deal event
curl --request POST \
  --url https://api.openquota.ai/v1/deals/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "external_id": "<string>",
  "state": {
    "amount_cents": 123,
    "stage": "<string>",
    "close_date": "<string>",
    "owner_external_id": "<string>"
  },
  "event_type": "upsert",
  "dedup_key": "<string>"
}
'
{
  "source_event_id": "<string>",
  "domain_event_id": "<string>",
  "deal_id": "<string>"
}
Push a new deal event into OpenQuota. This is the write path — call it every time a deal is created, moves stage, changes amount, or closes.

​
Idempotency

Retries with the same dedup_key are absorbed without side effects. The server uses it to short-circuit duplicate source events, domain events, and projection updates. In practice: put a stable value there (e.g. your system’s event ID plus a timestamp for create vs update), and retry freely on network errors. If you omit dedup_key, the server generates one from external_id + current timestamp. That works for ad-hoc pushes but defeats idempotency across retries, so provide one whenever you can.

​
The custom field

The state object accepts any fields beyond the standard set (amount_cents, stage, close_date, owner_external_id). Anything extra is preserved under state.custom and made available to your plan rules that reference custom fields. No field registration is required.

Authorizations

​
Authorization
string
header
required

Provide your API key as Authorization: Bearer <key>. Generate keys in the OpenQuota admin under Settings → API Keys.

Body

application/json
​
external_id
string
required

Stable ID for the deal in the caller's system.

Minimum string length: 1
​
state
object
required

The deal's current canonical state. Any fields beyond the standard set are preserved under state.custom.

​
event_type
enum<string>

Optional hint for downstream consumers. Defaults to 'upsert'.

Available options:
upsert,
stage_change,
amount_change,
delete
​
dedup_key
string

Deduplication key. If you retry with the same key, the event is absorbed idempotently.

Response

Event ingested. Returns the ids that were created.

​
source_event_id
string
required
​
domain_event_id
string
required
​
deal_id
string
required