Surveys

MATRADE-aligned exhibitor, conference and visitor surveys with results and CSV export.

Organisers run three post-event surveys for an event. Exhibitors answer once per company, signed in. Conference participants answer through a public link with no account. Visitors answer inside Visitor surveys; their questions are set there and only their results are read here. Added in contract 4.9.0.

MATRADE publishes no official survey form. The built-in templates follow the Market Development Grant Annex 2 (trade and public visitors, foreign buyers, total sales generated) and the Annex 7 outcome report (actual and potential sales, new markets, business opportunities). Templates are loaded by the Studio editor; the API stores whatever questions the organiser saves.

OperationAccessPurpose
GET /api/surveysOrganiserThe event's exhibitor and conference surveys, with a pointer to the visitor survey.
PUT /api/surveysOrganiserCreate or replace one audience's survey.
GET /api/surveys/resultsOrganiserPer-question summary for one audience.
GET /api/surveys/responsesOrganiserPaginated responses with labelled answers.
GET /api/surveys/exportOrganiserStream every response as CSV.
GET /api/surveys/exhibitorSessionA company's survey, read-only prefill and saved response.
POST /api/surveys/exhibitorSessionSubmit or update the company's response.
GET /api/surveys/publicPublicThe open conference survey for a link token.
POST /api/surveys/publicPublicSubmit a conference response.

Every response is private, no-store. Event inputs accept a slug or an event UUID; mutations take the event UUID. Every POST success is 201, including soft refusals that return an { error } body. GET and PUT success is 200. Cookie mutations need a trusted Origin.

Rules

  • Audiences. exhibitor and conference surveys are managed here. visitor is read-only here: its questions live on the visitor survey campaign, its answers on the visitor's spin entries.
  • Status. A survey is draft, open or closed. Opening needs at least one question (400). At most 40 questions. Only an open survey accepts answers.
  • Questions use the pass-form field types. Short text, long text, email, number, date, single choice, multiple choice and checkbox, validated with the same rules as registration pass forms.
  • Ratings are 1 to 5 single selects. A single select whose options run 1 – Poor to 5 – Excellent (or 1 – Very unlikely to 5 – Very likely) is summarised as a rating: its average and distribution. Other selects are counted per option. Number questions are totalled.
  • Number answers must be between 0 and one trillion.
  • Edits never rewrite history. Each response keeps the questions it was answered with, so reordering, relabelling or removing a question does not change past answers. Questions removed since a response stay in results and exports.
  • One response per company per event for exhibitors, and one per email per survey for the conference. Submitting again replaces the earlier response while the survey is open; the result's updated flag reports which happened.
  • Exports contain personal data and are recorded in the audit log.

Status codes by route group:

  • Organiser routes: 404 means the event was not found or is not in your scope. Owner, admin and staff of the event's organisation have access; crew do not. Draft events are allowed.
  • Exhibitor routes: 403 unless the caller is a live owner of the company, or a manager assigned to this exhibition. Staff and everyone else are refused. A company not exhibiting at the event returns 404. A cookie selecting a company is not authority.
  • Public routes: on GET, an unknown token returns 404, and so does a survey that is still a draft or has been closed, so a link reveals nothing about drafts. On POST, only an unknown token returns 404; a survey that is not open (draft or closed, including one closed after the page loaded) returns the 201 { error } body.

Organiser operations

GET /api/surveys?event=... returns { eventId, eventName, exhibitor, conference, visitor }. Each managed survey has id (null until first saved), status, title, fields, publicToken (conference only), responseCount and updatedAt. A survey that has never been saved comes back as a draft with no questions. visitor gives the visitor survey campaign status, its question count and its entry count.

PUT /api/surveys takes { eventId, audience, status, title, fields } and returns { ok: true, surveyId, publicToken } or { error }. The conference survey gets an unguessable link token on its first save; later saves never change it, so a printed QR keeps working. Closing the survey is how a link is retired.

GET /api/surveys/results?event=...&audience=... returns { audience, generatedAt, responseCount, questions }. Each question summary has kind (rating, choice, multi_choice, number or text), count of usable answers, average, distribution per option in option order, and for numbers total, min and max.

GET /api/surveys/responses?event=...&audience=... accepts cursor and returns { audience, responses, nextCursor }, newest first, 50 per page, each answer labelled from the questions that respondent saw. Visitor responses carry the attendee's name only. A malformed cursor returns 400.

GET /api/surveys/export?event=...&audience=... streams a CSV of every response, oldest first, with name, email, organisation, job title, timestamps and one column per question. Cells that could be read as spreadsheet formulas are neutralised. Handle the file like any export of personal data.

Exhibitor operations

GET /api/surveys/exhibitor?event=...&merchantId=... returns { eventId, eventName, survey, prefill, response }. survey is null while the organiser has not opened it. prefill holds the company name, contact name and email of the signed-in manager, and the booth, to show read-only. response is the company's saved answers; a closed survey shows them read-only.

POST /api/surveys/exhibitor takes { eventId, merchantId, answers } and returns { ok: true, updated, updatedAt } or { error } when the survey is not open or an answer is invalid.

Public operations

GET /api/surveys/public?token=... returns { eventName, title, status, fields } for an open survey. It never returns other respondents' answers. Reads are limited to 900 a minute per link token (429).

POST /api/surveys/public takes { token, name, email, organisation?, jobTitle?, answers } and returns { ok: true, updated } or { error }. Name and email are required; the email is lower-cased and keys the one-response rule. Responses are not verified: anyone holding the link who knows an email address can replace that address's earlier response, and updated reveals whether one existed. Treat results as self-reported. Limits (429): the same email on the same survey link may submit 10 times a minute, and one connecting address 1,500 calls a minute, so a room of several hundred people behind one venue network or one web server address can submit together. A hidden company_url_hp field is a honeypot: any value is treated as a bot, reported as success and stored nowhere.

Audit

Organiser and exhibitor actions write audit records naming the organisation and actor: surveys.saved, surveys.exported and surveys.exhibitor_submitted. Public submissions are not tied to an actor and are not audited.

Contract 4.9.0

Adds the nine operations above. No existing operation changes.

On this page