> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/client-api/surveys.md).

# Surveys

Survey methods live under `SL.client.surveys`. They all return promises and work with the [Survey object](https://docs.sparkloop.app/client-api/objects/survey.md).

The expected flow is: `fetch` → display → `submit`.

### Find your survey's uuid

Open your [Welcome Survey](https://dash.sparkloop.app/tools/survey) in the SparkLoop dashboard. The survey's ID is shown next to the title; click it to copy.

### fetch({ uuid })

Fetches the survey with its questions and promotions.

* `uuid` *(required)* — the survey's uuid.

Returns a [Survey](https://docs.sparkloop.app/client-api/objects/survey.md) object. Fetch it right before displaying it, so the promotions it includes are still available to the reader.

```js
const survey = await SL.client.surveys.fetch({ uuid: "survey_YOUR_SURVEY_UUID" });
```

Display `items` in order. Hide conditional items until their condition is met — see [Showing conditional items](#showing-conditional-items).

### submit({ uuid, email, answers, promotionUuids })

Submits the reader's answers and claims the promotions they chose.

* `uuid` *(required)* — the survey's uuid.
* `email` *(required)* — the reader's email address.
* `answers` — a list of `{ question_uuid, value }`, one per answered question.
* `promotionUuids` — the `uuid` of each promotion the reader chose. Use the promotion item's own `uuid`, not the `uuid` of the `offer` or `recommendation` inside it.

The answer `value` depends on the question's `input_type`:

* `text_input` — a string.
* `single_select` — one of the question's `options`.
* `multi_select` — a list of the question's `options`, up to `max_selections` when present.
* `checkbox` — `"Yes"` when checked. Leave the answer out when it isn't.

Returns `{ response: "ok" }`. The chosen promotions are claimed for the reader, the same way as `claim` and `subscribe`.

SparkLoop validates the whole submission before accepting it. Answers to questions hidden by their condition are ignored, so a hidden required question never blocks a submission. Each reader session can submit a survey once.

```js
SL.client.surveys.submit({ uuid, email, answers, promotionUuids })
  .then(() => showThankYou())
  .catch((error) => {
    if (error.code === "invalid_answers") {
      // error.details: [{ question_uuid: "survey_question_abc123", code: "blank", message: "can't be blank" }, ...]
      error.details.forEach(({ question_uuid, message }) => showQuestionError(question_uuid, message));
    } else {
      showGenericError(error.message);
    }
  });
```

### Invalid answers

When answers fail validation, `submit` rejects with an `invalid_answers` error (422). Its `details` lists one `{ question_uuid, code, message }` per problem:

* `blank` — a required visible question has no answer, or `question_uuid` doesn't match a question in the survey.
* `invalid_option` — the value isn't one of the question's `options`.
* `duplicate_option` — the same option was picked twice.
* `too_many_selections` — more options than `max_selections`.
* `not_a_list` — a `multi_select` answer that isn't a list.
* `not_a_single_value` — a list sent for a question that takes a single value.
* `not_checked` — a required `checkbox` answer that isn't `"Yes"`.
* `duplicate_question` — the same question was answered twice.

Show `message` next to the question with `question_uuid`, or your own copy based on `code`. Nothing is saved until the whole submission is valid.

{% hint style="danger" %}
Readers must explicitly choose the promotions you claim for them. Misleading readers into choosing promotions without their consent results in a permanent block of your SparkLoop account.
{% endhint %}

### Showing conditional items

Questions and promotions with a `condition` should only be shown once an earlier question has the given answer — see [Conditions](https://docs.sparkloop.app/client-api/objects/survey.md#conditions). An item is visible when it has no condition, or when its trigger question is itself visible and answered with the condition's `value`. Re-check visibility every time the reader changes an answer, and only send the answers and promotions that are visible when they submit.

```js
const survey = await SL.client.surveys.fetch({ uuid: "survey_YOUR_SURVEY_UUID" });
const answers = {};       // question uuid → the reader's current answer; update it from your inputs
const chosen = new Set(); // uuids of the promotions the reader chose; add/remove as they check them

function isVisible(item) {
  if (!item.condition) return true;

  const triggerQuestion = survey.items.find((other) => other.uuid === item.condition.question_uuid);
  // Hidden when the question it depends on is missing or is itself hidden
  if (!triggerQuestion || !isVisible(triggerQuestion)) return false;

  const answer = answers[triggerQuestion.uuid];
  // multi_select answers are lists; a checkbox answer is "Yes" when checked
  return Array.isArray(answer) ? answer.includes(item.condition.value) : answer === item.condition.value;
}

// Re-check every item whenever an answer changes, and only submit what is visible
await SL.client.surveys.submit({
  uuid: survey.uuid,
  email,
  answers: survey.items
    .filter((item) => item.type === "question" && isVisible(item) && item.uuid in answers)
    .map((item) => ({ question_uuid: item.uuid, value: answers[item.uuid] })),
  promotionUuids: survey.items
    .filter((item) => item.type === "promotion" && isVisible(item) && chosen.has(item.uuid))
    .map((item) => item.uuid),
});
```
