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 pathAuthorityBehaviour
GET /api/spin/meOptional sessionSurvey eligibility and the caller's latest non-voided entry.
POST /api/spinSessionSubmit the survey once per person per event.
GET /api/spin/campaignOrganiserSurvey setup and retained historical prize configuration.
PUT /api/spin/campaignOrganiserSave setup; surveyOnly: true preserves earlier prize and counter configuration.
GET /api/spin/statsOrganiserHistorical prize counts plus response counts by KL day.
GET /api/spin/entriesOrganiserPaginated responses and previous prize records.
GET /api/spin/exportOrganiserPrivate CSV with survey answers and previous prize records.
POST /api/spin/lookupCounter authorityFind historical entries through an authorised ticket lookup.
POST /api/spin/redeemCounter authorityRedeem an earlier winning entry once.
POST /api/spin/voidOrganiserVoid 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.

On this page