Ingest a deal event

Push a raw deal event into OpenQuota. Creates a source event, a normalized domain event, and upserts the deal projection. Safe to retry with the same dedup_key.

POST /deals/events

Ingest a deal event

cURL

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>"
}
'

201

{
  "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.

Show child attributes

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

201

application/json

Event ingested. Returns the ids that were created.

source_event_id · string · required

domain_event_id · string · required

deal_id · string · required