Survey Responses

A survey response is a single, completed submission to a survey. When a customer fills out your post-purchase survey and hits submit, that's one response — a record that ties together who answered (when known), which survey they answered, and every answer they gave. Responses are where the raw sentiment lives before it rolls up into an NPS score or a low-score alert.

Survey vs. response, in one line: a survey is the questionnaire you design; a response is one person's filled-out copy of it. You build and send surveys; you read and report on responses.

What a response holds #

Each response is deliberately thin — it's mostly a container that points at other things:

• Survey — the survey the response belongs to. Required; every response is anchored to exactly one survey.
• Invitation — the invitation that solicited it, when there is one. This is how a response gets a respondent email and a source (the record the invitation was sent about). Responses collected through an anonymous open link have no invitation, so they show no email.
• Answers — one entry per question the respondent addressed, each linking to the question and carrying the value they gave (see below).
• Submitted at — when the response came in, taken from when the record was created.

How answers are stored #

A response's answers are kept as individual records, one per question. Each answer can carry its value in one of three shapes, depending on the question type:

• a choice — the selected option's label, for multiple-choice questions,
• a numeric value — for scale or rating questions (star rating, NPS), or
• text — for free-form questions.

When a response is displayed or returned, the system shows whichever of these is set, falling back to a dash when a question was left blank.

Collecting responses #

Responses aren't created by hand inside the app — they arrive when respondents submit a survey. Two paths lead to a response:

• From an invitation — a survey invitation is sent to a customer (often about a specific record, its source), the customer follows the link and submits, and a response is recorded against both the survey and that invitation.
• From an anonymous open link — the survey's public link lets anyone submit without an invitation. These responses are still tied to the survey but have no respondent email or source.

Either way, the response and its answers are saved together, and the survey's NPS and response-rate reporting update accordingly.

Viewing responses #

Open Surveys → Responses for the list. Each row shows the survey, the respondent email (from the invitation, blank for anonymous submissions), the source of the invitation (e.g. an order or customer record, shown by type), and when it was answered. The list is sorted newest-first, and you can search by survey name or email.

Click any row to open the response. Its page shows the survey, respondent email, and submission time up top, then an Answers section listing every question alongside the answer that was given. Responses are read-only here — there's nothing to edit, because a response is a historical record of what someone submitted.

Responses are soft-deleted: removing one hides it from the list but keeps it in the database, so reporting history and audit trails stay intact.

How responses relate to surveys #

Responses are the payload of the Surveys module. A survey defines the questions and the delivery options; its responses are the answers that come back. The survey's NPS score and response-rate funnel are computed from its responses, and low-score alerts fire off the values inside them. To understand a number on a survey's report, drill into its responses.

Doing it from the API #

The survey-responses endpoint is read-only — you can list responses and fetch a single one, but you can't create, edit, or delete them over the API (responses come in through survey submission). Over the API, identifiers use _id field names (e.g. survey_id).

# List survey responses (optionally filter to one survey)
curl "https://your-domain.com/api/v1/survey-responses?survey_id=$SURVEY_ID" \
  -H "Authorization: Bearer $TOKEN"

# Get a single response with its answers
curl "https://your-domain.com/api/v1/survey-responses/{surveyResponse}" \
  -H "Authorization: Bearer $TOKEN"

Listing is paginated at 50 per page and accepts a survey_id query parameter to scope results to one survey. Each response returns its answers, with each answer carrying question_id and whichever of choice_id, answer_numeric, or answer_text applies.