> 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/api-v3/endpoints/publications/tools/surveys.md).

# Surveys

## Surveys

A **Survey** is a welcome survey a publication shows in its signup flow to collect subscriber profile data. Surveys are addressed by UUID and nested under a publication's `tools`, so the API can serve several per publication (a publication currently has at most one).

A survey's **questions** are a first-class sub-resource, and each question owns the feed of individual **answers** submitted to it. Completed **submissions** — one per subscriber, with every answer given — are a sibling sub-resource.

### List surveys

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys`

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "surveys": [
    <Survey Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 1,
    "total_surveys": 1
  }
}
```

{% endtab %}
{% endtabs %}

### Get survey

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:uuid`

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |
| uuid<mark style="color:red;">\*</mark>              | String | The survey's UUID.      |

**Query Parameters**

| Name   | Type   | Description                                             |
| ------ | ------ | ------------------------------------------------------- |
| expand | String | `stats` to include the survey step's completion funnel. |
| from   | String | Start date (`YYYY-MM-DD`) for `stats`.                  |
| to     | String | End date (`YYYY-MM-DD`) for `stats`.                    |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "survey": <Survey Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}
{% endtabs %}

### List questions

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions`

Questions are returned in ascending `position` order.

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |
| survey\_uuid<mark style="color:red;">\*</mark>      | String | The survey's UUID.      |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "questions": [
    <Survey Question Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 1,
    "total_questions": 4
  }
}
```

{% endtab %}
{% endtabs %}

### Get question

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions/:uuid`

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |
| survey\_uuid<mark style="color:red;">\*</mark>      | String | The survey's UUID.      |
| uuid<mark style="color:red;">\*</mark>              | String | The question's UUID.    |

**Query Parameters**

| Name   | Type   | Description                                                                   |
| ------ | ------ | ----------------------------------------------------------------------------- |
| expand | String | `stats` to include the per-option answer distribution. Select questions only. |

{% hint style="info" %}
`expand=stats` is only valid for select questions (`single_select`, `multi_select`). Requesting it on a text question returns `422` — read the individual answers via the answers feed instead.
{% endhint %}

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "question": <Survey Question Object>
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```json
{
  "error": "Text questions have no answer distribution. Fetch the individual answers instead."
}
```

{% endtab %}
{% endtabs %}

### List answers

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions/:question_uuid/answers`

A paginated, reverse-chronological feed of the individual answers to one question. Unlike the question's `stats` distribution, this includes text questions — for a free-text question it's the only way to read what subscribers submitted. No subscriber identity is included.

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |
| survey\_uuid<mark style="color:red;">\*</mark>      | String | The survey's UUID.      |
| question\_uuid<mark style="color:red;">\*</mark>    | String | The question's UUID.    |

**Query Parameters**

| Name   | Type   | Description                                                                                 |
| ------ | ------ | ------------------------------------------------------------------------------------------- |
| expand | String | `question` to inline the full question object on each answer (a UUID reference by default). |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "answers": [
    <Survey Answer Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 3,
    "total_answers": 128
  }
}
```

{% endtab %}
{% endtabs %}

### List submissions

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/submissions`

A paginated, reverse-chronological feed of completed submissions — one per subscriber, each with every answer given. No subscriber identity is included.

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |
| survey\_uuid<mark style="color:red;">\*</mark>      | String | The survey's UUID.      |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "submissions": [
    <Survey Submission Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 5,
    "total_submissions": 214
  }
}
```

{% endtab %}
{% endtabs %}

### Get submission

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/submissions/:uuid`

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |
| survey\_uuid<mark style="color:red;">\*</mark>      | String | The survey's UUID.      |
| uuid<mark style="color:red;">\*</mark>              | String | The submission's UUID.  |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "submission": <Survey Submission Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}
{% endtabs %}