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.

200: OK

{
  "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.

200: OK

{
  "survey": <Survey Object>
}

404: Not Found

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

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.

200: OK

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

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.

200: OK

{
  "question": <Survey Question Object>
}

422: Unprocessable Entity

{
  "error": "Text questions have no answer distribution. Fetch the individual answers 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).

200: OK

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

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.

200: OK

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

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.

200: OK

{
  "submission": <Survey Submission Object>
}

404: Not Found

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