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

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

GET https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys

Path Parameters

Name
Type
Description

publication_uuid*

String

The publication's UUID.

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

Get survey

GET https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:uuid

Path Parameters

Name
Type
Description

publication_uuid*

String

The publication's UUID.

uuid*

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.

List questions

GET 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*

String

The publication's UUID.

survey_uuid*

String

The survey's UUID.

Get question

GET https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions/:uuid

Path Parameters

Name
Type
Description

publication_uuid*

String

The publication's UUID.

survey_uuid*

String

The survey's UUID.

uuid*

String

The question's UUID.

Query Parameters

Name
Type
Description

expand

String

stats to include the per-option answer distribution. Select questions only.

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.

List answers

GET 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*

String

The publication's UUID.

survey_uuid*

String

The survey's UUID.

question_uuid*

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).

List submissions

GET 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*

String

The publication's UUID.

survey_uuid*

String

The survey's UUID.

Get submission

GET https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/submissions/:uuid

Path Parameters

Name
Type
Description

publication_uuid*

String

The publication's UUID.

survey_uuid*

String

The survey's UUID.

uuid*

String

The submission's UUID.