Quickstart

Open your organisation in Utilitay Account, then the Developers tab. Create a Menu key reaching the business you will call, with requests:read and decisions:write — and verifications:write if your counter checks codes. The key is shown once; send it as a bearer token on every request.

Authorization: Bearer utl_live_k3Jh9QpL2mZx7VbN4cRt8WyS1dFg6HaU0eIo5PqA3zK1a2B3c

A customer dials the business's code, walks a menu and submits. A request that waits for the business's answer is submitted. Poll the inbox, newest first; read one whole with /requests/retrieve when you need its lines, time and history.

[
  {
    "id": "4c8e2a71-9d3b-4f06-a5e2-1b7d9c3f8e54",
    "reference": "K7Q3MZ",
    "status": "submitted",
    "summary": "Braids, Long · Fri 9 Oct, 10:00 · Mary",
    "expires_at": "2026-10-07T14:02:11Z",
    "…": "…"
  }
]

Approving tells the customer and, where the business checks codes, gives them their six-digit code: by message where the business has linked Raven, otherwise the next time they dial in. Declining needs a reason, written for the customer: it goes in the message that tells them. A request someone else has already answered is refused with 409 already_decided.

When the customer arrives, they read out their code. Send it; a right code closes the request as verified, and the answer names who it is for and what they asked for. A wrong code is an answer too, with how many tries are left.

{
  "code": "482915"
}