POSTRecord an event
Requires events:write. Records the event and judges it: every rule that names the type answers in the same transaction. Send Idempotency-Key or event_ref so a retry records once.
type_key Varies by pack
Dues duedues_duescope: subject
- subject_id
- Required, or subject_ref
- group_id
- Forbidden
- date_field
- due_on
- dedupe_fields
- period
Body parameters
type_keystring · required
One of the types above.
subject_iduuid · required unless subject_ref
Raven's id for the membership. Decided by the type's scope (subject).
subject_refstring · required unless subject_id · max 200
The same membership, named by the reference you gave it: your own system knows MEM-2026-001, not Raven's id, so this saves it a lookup per event. Exactly one of the two.
occurred_atdatetime · optional
When it happened. Left out, now.
event_refstring · optional · max 200
Your own reference for this call; says what Idempotency-Key says.
payload
due_ondate · required
YYYY-MM-DD
paid_atdate · optional
YYYY-MM-DD
amount_centsmoney · required
Integer in cents · 50000 → 5,000.00
balance_centsmoney · optional
Integer in cents · 50000 → 5,000.00
Money fields are integers in cents. 50000 renders as 5,000.00. No currency symbol is sent or stored.
Returns
201 with the event as stored, one fire per rule judged, and sends: how many messages that made. A type nobody defined is a 400 that lists the ones that are; a broken scope rule or payload is a 400 that names the field. Naming the membership both ways is a 400, “Name the subject by subject_id or by subject_ref, not both.”, and a subject_ref nothing here holds is a 404. Everything after the reference is resolved is the same either way — the dedupe, the Idempotency-Key, the verdicts — and the event that comes back carries subject_id, so the answer tells you Raven's id.
Response body
One object: the same fields in every pack. Press Response on the sample to see one whole.
FieldTypeDescription
eventEventThe event as stored. Its fields are listed under it.
firesRuleFire[]One per rule that was judged against the event, whatever the verdict.
sendsintegerHow many sends that made: now, scheduled, or later in the send window.
batch_keystring | nullTies those sends together. null when there were none.
judgedintegerAlways 0 here; counts judgements on an internal replay.
Event event
FieldTypeDescription
iduuid
tenant_iduuidThe instance.
type_keystring
subject_iduuid | nullSet when the type's scope is subject — Raven's id, whether the call named the membership by subject_id or by subject_ref.
group_iduuid | nullSet when the type's scope is group.
occurred_atdatetimeAs sent, or when it was recorded.
effective_datedate | nullThe value of the type's date_field: what a rule in days counts from.
effective_atdatetime | nullThe same, where the date field is a date and time: what a rule in minutes counts from.
payloadobjectAs checked against the type's payload_schema.Varies by pack
dedupe_keystringMade from the type's dedupe_fields. The same key is the same event.
sourceapi | upload | manualapi for anything recorded with a key.
upload_iduuid | null
created_byuuid | nullThe key's id, for an event recorded through the API.
created_by_namestring | null“API key · ” and the key's name.
voided_atdatetime | nullSet once the event has been taken back.
voided_byuuid | null
void_reasonstring | null
voided_by_event_iduuid | nullSet when another event cleared this one, rather than a person or a key voiding it.
created_atdatetime
updated_atdatetime
Rule fire fires[]
FieldTypeDescription
iduuid
tenant_iduuid
rule_iduuid
event_iduuid | null
send_iduuid | nullThe send this verdict made, if it made one.
nudge_iduuid | null
outcomestringsent · scheduled · nudged · dry_run · not_matched · no_audience · no_wording · window_closed · already_fired · voided.
detailobjectWhy, in the rule's own terms.
fired_atdatetime
On failure the body is { error, code } instead.
