> 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/objects/survey.md).

# Survey

A welcome survey your reader can fill in. Returned by the [Surveys methods](https://docs.sparkloop.app/client-api/surveys.md).

| Field          | Type   | Description                                                                                                             |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `uuid`         | string | Unique identifier of the survey. Pass it back in `submit`.                                                              |
| `header`       | string | The survey's header.                                                                                                    |
| `subheader`    | string | The survey's subheader.                                                                                                 |
| `button_label` | string | Text for the submit button.                                                                                             |
| `skip_link`    | string | Text for the link that skips the survey.                                                                                |
| `custom_terms` | object | `{ enabled, text, url }`. When `enabled` is `true`, show `text` (linked to `url`, when present) near the submit button. |
| `items`        | array  | The survey's questions and promotions, in the order to display them. See below.                                         |

### Question items

| Field                        | Type    | Description                                                                                                                                                  |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`                       | string  | `question`.                                                                                                                                                  |
| `uuid`                       | string  | Unique identifier of the question. Use it as `question_uuid` when submitting answers.                                                                        |
| `label`                      | string  | The question's text.                                                                                                                                         |
| `input_type`                 | string  | `text_input`, `single_select`, `multi_select` or `checkbox`. Determines the answer format — see [Surveys](https://docs.sparkloop.app/client-api/surveys.md). |
| `required`                   | boolean | `true` when the reader must answer it (only while it's visible).                                                                                             |
| `options`                    | array   | The option labels to choose from, for `single_select` and `multi_select` questions. Empty otherwise.                                                         |
| `max_selections`             | integer | Only present on `multi_select` questions with a limit. The maximum number of options the reader can pick.                                                    |
| `system_question_identifier` | string  | Only present on built-in profile questions, e.g. `full_name`.                                                                                                |
| `autocomplete`               | string  | Only present on built-in profile questions. A value for the input's `autocomplete` attribute.                                                                |
| `html_type`                  | string  | Only present on built-in profile questions. A value for the input's `type` attribute, e.g. `tel`.                                                            |
| `condition`                  | object  | Only present on conditional items. See below.                                                                                                                |

### Promotion items

A promotion is an offer or a recommendation placed inside the survey, which the reader can choose to claim.

| Field            | Type   | Description                                                                                                                               |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `type`           | string | `promotion`.                                                                                                                              |
| `uuid`           | string | Unique identifier of the promotion. Pass it in `promotionUuids` when the reader chooses it.                                               |
| `kind`           | string | `offer` or `recommendation`.                                                                                                              |
| `offer`          | object | Only present when `kind` is `offer`. An [Offer object](https://docs.sparkloop.app/client-api/objects/offer.md).                           |
| `recommendation` | object | Only present when `kind` is `recommendation`. A [Recommendation object](https://docs.sparkloop.app/client-api/objects/recommendation.md). |
| `condition`      | object | Only present on conditional items. See below.                                                                                             |

Only promotions available to the current reader are included.

### Conditions

A conditional item is only shown when an earlier question has a given answer:

```json
{ "question_uuid": "survey_question_abc123", "value": "Marketing" }
```

Show the item when the question with `question_uuid` is answered with `value`. For a `multi_select` trigger, when `value` is one of the picked options. For a `checkbox` trigger, `value` is always `"Yes"`, meaning the box is checked. Hide it otherwise.

Items whose condition no longer works, because its question was deleted or its option removed, are left out of the survey.

### Example

```json
{
  "uuid": "survey_abc123",
  "header": "Complete your free subscription",
  "subheader": "Add your missing profile details and unlock our subscriber-only welcome offers.",
  "button_label": "Continue →",
  "skip_link": "No thanks →",
  "custom_terms": { "enabled": false, "text": null, "url": null },
  "items": [
    {
      "type": "question",
      "uuid": "survey_question_abc123",
      "label": "What do you do?",
      "input_type": "single_select",
      "required": true,
      "options": ["Marketing", "Engineering", "Other"]
    },
    {
      "type": "promotion",
      "uuid": "survey_promotion_def456",
      "kind": "offer",
      "condition": { "question_uuid": "survey_question_abc123", "value": "Marketing" },
      "offer": { "uuid": "offer_recommendation_9f8e7d6c5b4a", "headline": "Try Acme for free", "...": "..." }
    }
  ]
}
```
