Quickstart

Open your organisation in Utilitay Account, then the Developers tab. Create a Raven key with contacts:write, subjects:write, events:write and messages:read, reaching the instance you will call. The key is shown once; send it as a bearer token on every request.

Authorization: Bearer utl_live_k3Jh9QpL2mZx7VbN4cRt8WyS1dFg6HaU0eIo5PqA3zK1a2B3c

The subject is what events are about. The fixed fields are display_name and external_ref; everything inside attributes comes from the pack schema, and unknown keys are refused.

{
  "display_name": "Subject 001",
  "external_ref": "SUB-2026-001",
  "attributes": {}
}

The contact is the person who receives messages. A name and a phone number in E.164 are enough; WhatsApp or SMS is chosen per message by your rules. Where an instance takes contacts with no phone number, an email address and your own reference stand in its place.

{
  "name": "Hawa Kollie",
  "phone_e164": "+231881872270",
  "attributes": {}
}

A link says which contacts hear about a subject. It upserts on the pair. The relationship field is required when the pack offers a choice, and filled in for you when it offers one value.

{
  "contact_id": "0d6c1e7a-3b52-4f8e-a1d9-6c2b7e4f8a31",
  "subject_id": "8a3f5d21-9c6e-4b17-8e02-1d4a7c9b3f56",
  "is_primary": true
}

This is the call that makes Raven send. It validates the payload against the type, dedupes on your reference and the type’s dedupe fields, judges it against your rules, and queues the messages. The response tells you what fired.

{
  "type_key": "…",
  "subject_id": "8a3f5d21-9c6e-4b17-8e02-1d4a7c9b3f56",
  "payload": {}
}

Messages are read only. Each carries the channel, the body as it went and a delivery status that moves as WhatsApp and SMS report back.