For the complete documentation index, see llms.txt. This page is also available as Markdown.

Surveys

Survey methods live under SL.client.surveys. They all return promises and work with the Survey object.

The expected flow is: fetch → display → submit.

Find your survey's uuid

Open your Welcome 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 object. Fetch it right before displaying it, so the promotions it includes are still available to the reader.

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.

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.

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.

Showing conditional items

Questions and promotions with a condition should only be shown once an earlier question has the given answer — see 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.