Fetch Surveys

List the surveys of the authenticated account with their question, page and response counters.

POST https://api-v3.sweeppea.com/surveys/fetch

Description

This endpoint returns a paginated list of surveys, newest first, together with the counters needed to decide what to do next: how many questions each survey holds, how many pages it spans and how many responses it has collected. Every row carries the public link rendered by the HUB, so a listing is enough to distribute a survey. The IsLocked flag is derived at read time and never stored — a survey is locked once it has at least one response, and from that moment its question set can no longer be replaced through /surveys/update. The counters are aggregated for the returned page only, so the call cost does not grow with the size of the account.

Authentication

This endpoint requires Bearer token authentication via the Authorization header.

Request Body

Field	Type	Required	Description
`SweepstakesToken`	String	No	UUID v4. Only the surveys of that sweepstakes
`Status`	Boolean	No	`true` returns enabled surveys, `false` disabled ones. Omit to get both
`Archived`	Boolean	No	Filter by the archived flag. Omit to get both
`Page`	Number	No	Page number (default: 1)
`Limit`	Number	No	Results per page (default: 50, maximum: 200)

Code Examples

curl -X POST "https://api-v3.sweeppea.com/surveys/fetch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "SweepstakesToken": "uuid-v4-string",
        "Status": true,
        "Page": 1,
        "Limit": 25
    }'

const response = await fetch('https://api-v3.sweeppea.com/surveys/fetch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SweepstakesToken: "uuid-v4-string",
    Status: true,
    Page: 1,
    Limit: 25
})
});

const data = await response.json();
console.log(data);

import requests

url = "https://api-v3.sweeppea.com/surveys/fetch"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "SweepstakesToken": "uuid-v4-string",
    "Status": True,
    "Page": 1,
    "Limit": 25
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response

{
  "Response": true,
  "Telemetry": {
    "DataConsumed": 0,
    "APICalls": 204,
    "MaxAPICalls": 1500000
  },
  "Data": {
    "Surveys": [
      {
        "SurveyToken": "uuid-v4-string",
        "SweepstakesToken": "uuid-v4-string",
        "SweepstakesName": "Tesla Model 3",
        "SurveyName": "Post-Purchase Feedback",
        "CreationDate": "2026-07-31T14:02:11.004Z",
        "QuestionsCount": 3,
        "PagesCount": 2,
        "ResponsesCount": 268,
        "IsLocked": true,
        "Settings": {
          "QuestionsPerPage": 2,
          "ShowProgressBar": true,
          "Language": "en",
          "LogoFile": null
        },
        "PublicLink": "https://hub.sweeppea.com/s?tkn=uuid-v4-string",
        "Archived": false,
        "Status": true
      }
    ],
    "Pagination": {
      "Page": 1,
      "Limit": 25,
      "TotalSurveys": 1,
      "TotalPages": 1
    }
  },
  "Message": "Surveys fetched successfully."
}

Error Responses

{
  "Response": false,
  "Message": "Invalid SweepstakesToken. It must be a valid UUID v4 string.",
  "Code": 400,
  "Help": {
    "ExpectedBody": {
      "SweepstakesToken": "string (optional) \u2014 UUID v4. Only surveys of that sweepstakes"
    }
  }
}

{
  "Response": false,
  "Message": "Missing or invalid Bearer token. Send your API token in the Authorization header as: Authorization: Bearer YOUR_API_TOKEN",
  "Code": 401
}

{
  "Response": false,
  "Message": "Invalid API token. It does not match any account.",
  "Code": 403
}

{
  "Response": false,
  "Message": "Internal server error. Please try again; if it persists, contact support with the time of this request.",
  "Code": 500
}

Important Notes

Every filter is optional — an empty body returns the whole account, 50 rows at a time.
Results are always scoped to the account that owns the API token. Another account's surveys are never visible.
PagesCount is the highest page actually holding a question, not the number of pages configured.
Settings never carries the base64 buffer of an uploaded file. Visuals (the look of the public form) is included, so what you set through /surveys/create or /surveys/update can be read back.
PublicLink is the HUB address the participant answers on: https://hub.sweeppea.com/s?tkn={SurveyToken}.
For one survey with its questions, use POST /surveys/single.
🔒 Module Access: The Surveys module is disabled by default. An administrator must enable it for your account before any of these endpoints will respond.