Create Survey

Create a survey together with its whole question set in one call.

POST /surveys/create

Description

A survey always belongs to a user AND a sweepstakes, so SweepstakesToken is required and is verified against the account that owns the API token. Pagination is implicit: the Page you put on each question is a grouping key, not a stored page number. The distinct pages are renumbered 1..N with no gaps and Order is the position inside the array, per page — sending pages 1, 5 and 9 produces pages 1, 2 and 3. Nothing is written unless the entire payload validates, so a rejected call never leaves a half-created survey behind.

Authentication

This endpoint requires Bearer token authentication via the Authorization header.

Request Body

Field	Type	Required	Description
`SweepstakesToken`	String	Yes	UUID v4 of the sweepstakes the survey belongs to
`SurveyName`	String	Yes	Survey name, up to 200 characters
`Status`	Boolean	No	`false` creates the survey disabled (default: `true`)
`Settings`	Object	No	Optional survey settings. Accepted keys: `Description`, `QuestionsPerPage` (1-5), `CollectContactInfo`, `ShowProgressBar`, `ShuffleQuestions`, `AllowMultipleResponses`, `ThankYouMessage`, `RedirectUrl`, `StartDate`, `EndDate`, `MaxResponses`, `ShowCountdown`, `EnableSharing`, `Language` (`en` or `es`). Visual keys (`Visuals`, `Pages`, `LogoFile`) are managed in the app and ignored here
`Questions`	Array	No	The question set. Each item accepts `Page`, `QuestionText` (required), `QuestionDescription`, `FieldType` (required, one of `text`, `textarea`, `radio`, `checkbox`, `select`, `slider`, `rating`, `nps`, `yesno` or `date`), `Layout`, `Required`, `Options[]` and `Settings{}`. Omit or send `[]` to create an empty survey

curl -X POST "https://api-v3.sweeppea.com/surveys/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "SweepstakesToken": "uuid-v4-string",
        "SurveyName": "Post-Purchase Feedback",
        "Settings": {
            "QuestionsPerPage": 2,
            "ShowProgressBar": true,
            "Language": "en"
        },
        "Questions": [
            {
                "Page": 1,
                "QuestionText": "How did you hear about us?",
                "FieldType": "radio",
                "Required": true,
                "Options": [
                    {
                        "Label": "Friend"
                    },
                    {
                        "Label": "Social media"
                    }
                ]
            },
            {
                "Page": 1,
                "QuestionText": "Rate our checkout",
                "FieldType": "rating",
                "Settings": {
                    "RatingMax": 5,
                    "RatingIcon": "star"
                }
            },
            {
                "Page": 2,
                "QuestionText": "Anything we should improve?",
                "FieldType": "textarea"
            }
        ]
    }'

const response = await fetch('https://api-v3.sweeppea.com/surveys/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SweepstakesToken: "uuid-v4-string",
    SurveyName: "Post-Purchase Feedback",
    Settings: {
        "QuestionsPerPage": 2,
        "ShowProgressBar": true,
        "Language": "en"
    },
    Questions: [
        {
            "Page": 1,
            "QuestionText": "How did you hear about us?",
            "FieldType": "radio",
            "Required": true,
            "Options": [
                {
                    "Label": "Friend"
                },
                {
                    "Label": "Social media"
                }
            ]
        },
        {
            "Page": 1,
            "QuestionText": "Rate our checkout",
            "FieldType": "rating",
            Settings: {
                "RatingMax": 5,
                "RatingIcon": "star"
            }
        },
        {
            "Page": 2,
            "QuestionText": "Anything we should improve?",
            "FieldType": "textarea"
        }
    ]
})
});

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

import requests

url = "https://api-v3.sweeppea.com/surveys/create"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "SweepstakesToken": "uuid-v4-string",
    "SurveyName": "Post-Purchase Feedback",
    "Settings": {
        "QuestionsPerPage": 2,
        "ShowProgressBar": True,
        "Language": "en"
    },
    "Questions": [
        {
            "Page": 1,
            "QuestionText": "How did you hear about us?",
            "FieldType": "radio",
            "Required": True,
            "Options": [
                {
                    "Label": "Friend"
                },
                {
                    "Label": "Social media"
                }
            ]
        },
        {
            "Page": 1,
            "QuestionText": "Rate our checkout",
            "FieldType": "rating",
            "Settings": {
                "RatingMax": 5,
                "RatingIcon": "star"
            }
        },
        {
            "Page": 2,
            "QuestionText": "Anything we should improve?",
            "FieldType": "textarea"
        }
    ]
}

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

Response

201 Created

				{
  "Response": true,
  "Telemetry": {
    "DataConsumed": 0,
    "APICalls": 204,
    "MaxAPICalls": 1500000
  },
  "Data": {
    "SurveyToken": "uuid-v4-string",
    "SweepstakesToken": "uuid-v4-string",
    "SweepstakesName": "Tesla Model 3",
    "SurveyName": "Post-Purchase Feedback",
    "QuestionsCount": 3,
    "PagesCount": 2,
    "Settings": {
      "QuestionsPerPage": 2,
      "ShowProgressBar": true,
      "Language": "en",
      "LogoFile": null
    },
    "PublicLink": "https://hub.sweeppea.com/s?tkn=uuid-v4-string",
    "Status": true,
    "Archived": false
  },
  "Message": "Survey Created Successfully"
}
			

Error Responses

400 Bad Request

				{
  "Response": false,
  "Message": "Missing required parameter: SweepstakesToken",
  "Code": 400,
  "Help": {
    "ExpectedBody": {
      "SweepstakesToken": "string (required) \u2014 UUID of the sweepstakes",
      "SurveyName": "string (required) \u2014 Name of the survey"
    }
  }
}
			

400 Bad Request

				{
  "Response": false,
  "Message": "Question at position 2 is invalid. QuestionText is required and FieldType must be one of: text, textarea, radio, checkbox, select, slider, rating, nps, yesno, date.",
  "Code": 400
}
			

400 Bad Request

				{
  "Response": false,
  "Message": "Page 1 holds 3 questions but the maximum is 2. Adjust Settings.QuestionsPerPage or move questions to another page.",
  "Code": 400
}
			

401 Unauthorized

				{
  "Response": false,
  "Message": "Invalid or Missing Bearer Token",
  "Code": 401
}
			

403 Forbidden

				{
  "Response": false,
  "Message": "Invalid API Token",
  "Code": 403
}
			

403 Forbidden — account-wide plan cap reached (see MaxSurveysAllowed in Plan Details).

				{
  "Response": false,
  "Message": "Surveys Limit Reached. Your plan allows 3 survey(s) across the whole account and you currently have 3. Please upgrade your plan to create more surveys",
  "Code": 403
}
			

404 Not Found

				{
  "Response": false,
  "Message": "Sweepstakes not found. It must exist and belong to your account.",
  "Code": 404
}
			

500 Internal Server Error

				{
  "Response": false,
  "Message": "Internal Server Error",
  "Code": 500
}
			

Important Notes

Structural limits: 5 questions per page (or Settings.QuestionsPerPage, whichever is lower), 50 pages, 250 questions and 30 options per question.
The pages you send are grouping keys. They are renumbered 1..N with no gaps, and Order is assigned from the position inside the array.
Nothing is written unless every question validates — DocumentDB gives no multi-document transaction to roll back with.
The survey token and every question token are minted in a single batch, so creating a 25-question survey costs two round trips instead of 25 collection scans.
Visual settings (Visuals, Pages, LogoFile) are silently ignored — they are uploaded and styled in the app, and accepting them here would let an integration clobber an uploaded file object.
The survey is created enabled unless Status: false is sent, and always unarchived.
To change the question set afterwards use POST /surveys/update — but only while the survey has no responses.
🔒 Module Access: The Surveys module is disabled by default. An administrator must enable it for your account before any of these endpoints will respond.

Sweeppea API v3

Sweeppea API v3

Create Survey

Description

Authentication

Request Body

Code Examples

Response

Error Responses

Important Notes