Concepts

Requests and codes

A customer dials the business's code, picks a menu and answers its screens: what, where, with whom, when, about you. The last screen submits a request. Everything after that — the answer, the code, the visit — moves the request through its statuses, and every move is kept in its history.

Statuses

Two are open, and hold the request's time: submitted and approved. The rest are closed, for good: closed_at is set and the time is freed. Every request closes, on its own if nobody closes it.

submittedopenWaits for the business's answer: its menu approves first, or the request is over the menu's self-served limit. Unanswered by expires_at, it expires.

approvedopenConfirmed. A self-served request starts here. Its time is held, and where the business checks codes the customer has one.

verifiedclosedThe customer's code was checked: they came, and were served.

completedclosedDone without a code: the business marked it done, or its fulfil_by passed on a request with codes off.

unclaimedclosedCodes on, and nobody came with the code by fulfil_by.

cancelledclosedCalled off, by the customer or by the business, with a reason.

declinedclosedThe business said no, with a reason the customer is told.

expiredclosedNobody answered in time.

Codes

A code proves the person at the counter is the one who asked. It is six digits, made when a request is approved where its menu checks codes (codes_on). Menu keeps only its hash: nobody, Menu included, can read one back, so no API answer ever carries one. The customer gets it by message where the business has linked Raven, otherwise on their phone the next time they dial in.

Staff ask for the code before serving, and POST /requests/verify checks it. A right code closes the request as verified in one step. It matches only an approved request due now, so a code from last week, or for next week, is wrong today. Wrong codes are counted per key: after the business's limit the key is locked out for a while, and the answer says until when.

Who is told

Menu never messages anyone itself. Each move writes an event to the request's history, and where the business has linked Raven, Raven tells the customer (approved, declined, moved, cancelled, due) and the business's staff (a new request, one still waiting), in the business's own wording. history[].handoff says whether each one reached Raven; not_linked means nobody was told by message.

Instances

An instance is one business, and its slug is the one on the path: /menu/v1/t/mamas-salon/…. A business may run several branches in one instance; then each request names its branch_id. A key reaches the instances chosen when it was made, and to a key, an instance it does not reach is simply not there: 404.

Previous← Quickstart NextAuthentication, keys and scopes →