Visitor surveys
Survey-only visitor submissions and historical prize redemption through retained API paths.
API 5.0.0 removes new prize allocation. Registered visitors answer the survey
and receive a completion confirmation. Existing /api/spin paths and response
envelopes remain for compatibility with printed links and saved clients. Clients
must replace wheel and prize promises with survey completion. This is a major
behaviour change, deployed to production on 7 October 2026.
| Method and path | Authority | Behaviour |
|---|---|---|
GET /api/spin/me | Optional session | Survey eligibility and the caller's latest non-voided entry. |
POST /api/spin | Session | Submit the survey once per person per event. |
GET /api/spin/campaign | Organiser | Survey setup and retained historical prize configuration. |
PUT /api/spin/campaign | Organiser | Save setup; surveyOnly: true preserves earlier prize and counter configuration. |
GET /api/spin/stats | Organiser | Historical prize counts plus response counts by KL day. |
GET /api/spin/entries | Organiser | Paginated responses and previous prize records. |
GET /api/spin/export | Organiser | Private CSV with survey answers and previous prize records. |
POST /api/spin/lookup | Counter authority | Find historical entries through an authorised ticket lookup. |
POST /api/spin/redeem | Counter authority | Redeem an earlier winning entry once. |
POST /api/spin/void | Organiser | Void an earlier unredeemed winning entry. |
Visitor submission
A confirmed visitor registration is required. No check-in is required. The event
must be published and its survey campaign open. Missing/draft campaigns return
closed eligibility; signed-out viewers of open campaigns receive sign_in.
Unknown or unpublished events return 404.
GET /api/spin/me returns { eventId, campaign, eligibility, entry }. An open
campaign's prizes array is empty and nextDay is omitted. Stock cannot block the
survey. Entries from an earlier day remain visible, including historical prizes.
POST /api/spin accepts { eventId, answers }. On success it returns
{ entry, wheel: [] }. New entries have prize: null. No prize stock is read,
reserved or consumed. The API validates required fields and preserves a snapshot
of the questions with each response. Invalid answers or ineligible submissions
return { error } with the existing 201 status. Cookie mutations require a
trusted Origin.
A transaction and per-person advisory lock make retries idempotent across event days. An existing non-voided entry is returned unchanged, so it keeps its previous answers and any historical prize. A same-day voided row still occupies the per-day uniqueness slot; submitting again that day returns a recovery message. No response, prize or redemption history is deleted by this change.
Historical prize operations
Owner, admin and staff organisers can access records for their own event. Crew
need a live assignment to the configured counter zone. These permissions are
checked by the API on every request. Closing the campaign does not prevent
redemption of an earlier winning entry. Concurrent redemption is conditional:
only one request succeeds; later requests report already_redeemed with the
stored time and redeemer. Other outcomes are no_prize and voided.
Organiser exports contain names and survey answers, require live authority and are private/no-store. Question snapshots preserve labels for questions removed from later survey revisions. CSV values are escaped against spreadsheet formulas. The Surveys API continues to include these visitor responses in results and MATRADE figures.

