API reference
Requests
/requests
What a customer's walk through a menu ends in: what they asked for, when, where and for whom. Read the inbox, answer what waits, check a customer's code at the counter, and change what is booked. Every move here is the one the dashboard and the staff phone menu make, under the same rules, and the customer is told by message where the business has linked Raven.
GET/requests/listThe inboxGET/requests/retrieve/{request_id}One request, wholePOST/requests/approve/{request_id}Say yesPOST/requests/decline/{request_id}Say no, with a reasonshown →POST/requests/verifyCheck a customer's codePOST/requests/cancel/{request_id}Call it offPOST/requests/reschedule/{request_id}Move it to another timePOST/requests/reassign/{request_id}Give it to someone else
POSTDecline a request
Requires decisions:write. For a request that is submitted. The reason goes to the customer in the message that tells them, so write it for them. Its time is freed at once. Refused with 409 already_decided when the request has moved on: someone else answered first, or it expired.
Path parameters
request_iduuid · required
The request's id, from the list or a staff alert.
Body
reasonstring · required · 1–200
“Fully booked that day.”
Returns
The request as it now is: the same body as GET /requests/retrieve.
Response body
One request: press Response on the sample to see one whole.
FieldTypeDescription
iduuid
tenant_iduuidThe business.
menu_iduuid
menu_version_iduuidThe published version the customer walked: a menu changed since does not change the request.
category_idstring | nullbooking, ordering, registration, rentals, hires: one of the catalogue's categories.
branch_iduuid | null
customer_iduuid | null
statussubmitted | approved | verified | completed | unclaimed | cancelled | declined | expired
channelussd | whatsapp
referencestringSix characters from 2–9 and A–Z without I and O.
session_refstring | nullThe network's session id, so a session submits once.
answersobjectA copy of every screen answered, for display. lines, times, places and party are what Menu acts on.
detailsobjectThe answers to the menu's own Details questions, by key.
summarystring
total_centsinteger | null
pricedboolean
quote_centsinteger | null
quote_notestring | null
approval_modeapprove_first | self_served | self_served_limitAs it was when the request was made.
codes_onboolean
code_issued_atdatetime | nullWhen the customer's current code was made. The code itself is never shown: only its hash is kept.
code_delivered_atdatetime | nullWhen it last left Menu for the customer.
code_reissuesinteger
service_atdatetime | null
service_enddatetime | null
fulfil_bydatetime | nullWhile approved: when it closes on its own, as unclaimed or completed.
expires_atdatetime | null
submitted_atdatetime
decided_atdatetime | null
decided_by_kindcustomer | staff | user | api | system | null
decided_by_refstring | nullFor a key: its id.
decided_by_namestring | null
decline_reasonstring | null
verified_atdatetime | null
verified_by_refstring | null
verified_by_namestring | null
cancelled_bycustomer | staff | user | api | system | null
cancel_reasonstring | null
closed_atdatetime | null
staff_told_atdatetime | nullWhen the business's staff were first told of it.
waiting_told_atdatetime | nullWhen staff were reminded it still waits.
due_told_atdatetime | nullWhen the customer was reminded it is due.
overdue_told_atdatetime | null
created_atdatetime
updated_atdatetime
linesLine[]The What: each offering asked for.
timesTime[]The When and the With whom. Empty for a request with no time.
placesPlace[]The Where. Empty where the menu does not ask.
partyParty | nullThe About you.
identityIdentity[]ID and licence numbers the menu asked for, masked.
historyHistoryEntry[]Everything that happened to it, oldest first.
customerRequestCustomer | nullThe phone behind it. Absent once the customer's record has been erased.
Line
FieldTypeDescription
iduuid
tenant_iduuidThe business.
request_iduuid
positionintegerOrder within the request.
offering_iduuid | nullThe catalogue offering. null once that offering is deleted; the line keeps its name and price.
namestringAs it was when the request was made.
price_centsinteger | nullCents, as it was at the time. null: the offering has no fixed price and the business quotes one.
price_uniteach | per_day | per_hour | per_person
quantityinteger1 unless the menu asks how many.
extrasarrayThe add-ons chosen: [{extra_id, name, price_cents}].
line_centsinteger | nullThis line's amount: price times quantity (and length, for a rate), plus extras.
Time
FieldTypeDescription
step_keystringThe menu step that asked.
precisionday | day_part | window | exact | days | sessionWhat the business promised: a day, a part of a day, a window, an exact time, several days, or a session.
daydateThe first day, at the business.
day_part_iduuid | nullFor day_part.
session_iduuid | nullFor session.
resource_iduuid | nullWho or what does it, when the menu asked or the business assigned one.
starts_atdatetimeEvery precision is a range: a day runs midnight to midnight at the business.
ends_atdatetime
seatsintegerPlaces taken: more than 1 for a party in a session.
Place
FieldTypeDescription
iduuid
tenant_iduuid
request_iduuid
step_keystringA delivery has two: pickup and drop-off.
place_iduuid | null
area_iduuid | nullThe broader area chosen first, when the menu narrows by area.
namestringAs it was at the time.
specificsstring | nullWhat the customer typed: a house, a landmark. 160 characters at most.
charge_centsintegerWhat the place adds, in cents.
off_sitebooleantrue when the business goes to the customer.
Party
FieldTypeDescription
namestring | nullThe name given for this request.
party_sizeintegerHow many people.
for_someone_elsebooleanAsked on behalf of someone: an agent, a parent, a secretary.
requester_namestring | nullWho asked, when it was for someone else.
Identity
FieldTypeDescription
labelstringWhat the menu asked for: “National ID”, “Driver’s licence”.
maskedstringThe last three characters, after ***. The number itself never leaves Menu.
HistoryEntry
FieldTypeDescription
idintegerAscending: the order things happened in.
kindstringrequest_submitted, request_approved, request_changed, staff_request_new, code_reissued…
from_statusstatus | null
to_statusstatus | nullSet where the status changed.
actor_kindcustomer | staff | user | api | systemapi: a key, as yours is.
actor_namestring | nullA key is named “API key · {its name}”.
reasonstring | nullA decline's or a cancel's reason.
detailobjectWhat changed, for request_changed: {change, was}.
atdatetime
handoffpending | sent | skipped | not_linked | failedWhether the message it causes reached Raven. not_linked: the business has no Raven link, so nobody is told by message.
handed_atdatetime | null
handoff_resultobject | nullWhat the hand-off found: Raven's outcome and the type it was recorded as, or a code saying why nobody was told (nobody_to_tell, a link's reason).
RequestCustomer
FieldTypeDescription
iduuid
phone_e164stringThe phone that made the request.
namestring | nullThe last name this phone gave. null once the business has forgotten it.
wa_opt_inboolean | nullWhether they said yes to WhatsApp messages. null: never asked.
requestsintegerHow many requests this phone has made here, this one included.
sincedatetimeWhen this phone first reached the business.
Amounts are integers in cents, with no currency. On failure the body is { error, code } instead.