UtilitayDevelopers
Ravenraven
Get an API key
API reference

Events

/events

Posting an event is what makes Raven send. Types come from the High school pack and from your instance; GET /event-types is the truth for your instance.

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
Absenceabsencescope: subject
subject_id
Required, or subject_ref
group_id
Forbidden
date_field
date
dedupe_fields
date, session
Body parameters
type_keystring · required
One of the types above.
subject_iduuid · required unless subject_ref
Raven's id for the student. Decided by the type's scope (subject).
subject_refstring · required unless subject_id · max 200
The same student, named by the reference you gave it: your own system knows STU-2026-001, not Raven's id, so this saves it a lookup per event. Exactly one of the two.
group_iduuid · forbidden
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
datedate · required
YYYY-MM-DD
reasontext · optional
sessionchoice · required
am · pm · full
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 student 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 student 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.