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— theuuidof each promotion the reader chose. Use the promotion item's ownuuid, not theuuidof theofferorrecommendationinside it.
The answer value depends on the question's input_type:
text_input— a string.single_select— one of the question'soptions.multi_select— a list of the question'soptions, up tomax_selectionswhen 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, orquestion_uuiddoesn't match a question in the survey.invalid_option— the value isn't one of the question'soptions.duplicate_option— the same option was picked twice.too_many_selections— more options thanmax_selections.not_a_list— amulti_selectanswer that isn't a list.not_a_single_value— a list sent for a question that takes a single value.not_checked— a requiredcheckboxanswer 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.