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.
| Operation | Access | Purpose |
|---|---|---|
GET /api/surveys | Organiser | The event's exhibitor and conference surveys, with a pointer to the visitor survey. |
PUT /api/surveys | Organiser | Create or replace one audience's survey. |
GET /api/surveys/results | Organiser | Per-question summary for one audience. |
GET /api/surveys/responses | Organiser | Paginated responses with labelled answers. |
GET /api/surveys/export | Organiser | Stream every response as CSV. |
GET /api/surveys/exhibitor | Session | A company's survey, read-only prefill and saved response. |
POST /api/surveys/exhibitor | Session | Submit or update the company's response. |
GET /api/surveys/public | Public | The open conference survey for a link token. |
POST /api/surveys/public | Public | Submit 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.
exhibitorandconferencesurveys are managed here.visitoris read-only here: its questions live on the visitor survey campaign, its answers on the visitor's spin entries. - Status. A survey is
draft,openorclosed. 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 – Poorto5 – Excellent(or1 – Very unlikelyto5 – 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
updatedflag reports which happened. - Exports contain personal data and are recorded in the audit log.
Status codes by route group:
- Organiser routes:
404means 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:
403unless 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 returns404. A cookie selecting a company is not authority. - Public routes: on
GET, an unknown token returns404, and so does a survey that is still a draft or has been closed, so a link reveals nothing about drafts. OnPOST, only an unknown token returns404; a survey that is not open (draft or closed, including one closed after the page loaded) returns the201{ 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.

