Skip to content

create-wizard.md

Latest commit

 

History

History
382 lines (335 loc) · 13.5 KB

create-wizard.md

File metadata and controls

382 lines (335 loc) · 13.5 KB

Create Rules via Wizard

Create official rules for a sweepstakes using the 14-step wizard flow. This endpoint takes structured wizard answers as input, generates the complete official rules HTML document server-side, and saves the result. The first rule created for a sweepstakes will be marked as primary.

Endpoint

POST /rules/createWizard

Description

This endpoint replicates the Official Rules Wizard from the Sweeppea frontend application. It follows a 14-step process (Steps A through N) that collects sweepstakes details and generates a complete legal document (HTML) for official rules.

Unlike the /rules/create endpoint which requires you to provide pre-built HTML content, this endpoint generates the document automatically from structured data. This is ideal for API integrations, MCP tools, and automated workflows.

Wizard Steps: A = Welcome, B = ARV Check, C = Alcohol, D = Promo Name, E = Start/End Dates, F = Prize Details, G = Prize Value, H = Winners/Entry Periods, I = Sponsor Info, J = Entry Method, K = Minimum Age, L = States Eligibility, M = Privacy Policy, N = Entry Page

Authentication

This endpoint requires Bearer token authentication via the Authorization header.

Request Parameters - Required Fields

Parameter Type Step Description
SweepstakesToken String (UUID v4) - The unique identifier of the target sweepstakes
Arv Number (1|2) B 1 = Total ARV >= $5,000, 2 = Total ARV < $5,000
AlcoholSweeps Number (1|2) C 1 = Alcohol-related sweepstakes, 2 = Not alcohol-related
SweepstakesName String (6-60 chars) D Official promotional name of the sweepstakes
StartDate String (YYYY-MM-DD) E Sweepstakes start date
StartTime String E Start time (e.g., "09:00 AM" or "14:00")
StartTimezone String E Timezone (e.g., "US/Eastern", "EST", "CST")
EndDate String (YYYY-MM-DD) E Sweepstakes end date
EndTime String E End time (e.g., "11:59 PM" or "23:59")
EndTimezone String E Timezone for end date
PrizeDescription String (max 5000) F Full description of all prize(s) being offered
PrizeIncludeTravel Boolean F true = Prize includes travel, false = No travel
PrizeIsVehicle Boolean F true = Prize is a vehicle, false = Not a vehicle
PrizeValue Number (> 0) G Approximate Retail Value of all prizes combined (USD)
EntryPeriodSelector Number (1|2) H 1 = Single drawing, 2 = Multiple entry periods
SponsorName String I Legal name of the sweepstakes sponsor
SponsorAddress String I Street address of the sponsor
SponsorCity String I City where the sponsor is located
SponsorState String I US state name or abbreviation
SponsorZipCode String (5 digits) I 5-digit ZIP code (e.g., "33131")
MethodOfEntry Number (1-8) J 1=Website, 2=SMS, 3=Social Media, 4=Other, 5=Purchase($1=1entry), 6=Purchase(1order=1entry), 7=Donation, 8=Subscription
MinAgeOfParticipation Number (1|2|3) K 1 = 18+, 2 = 21+, 3 = 13+ (with parental consent)
StatesAbleToParticipate Number (1-10) L Geographic eligibility (see Eligibility Options below)
PrivacyPolicyURL String (min 11 chars) M Full URL to privacy policy (must include http/https)
SweeppeaEntryPage Number (1|2|3) N 1=Sweeppea entry page, 2=Custom entry page, 3=No entry page

Request Parameters - Conditional Fields

These fields are required only when certain conditions are met.

Parameter Type Required When Description
WinnersToDraw Number (>= 1) EntryPeriodSelector = 1 Number of winners to draw
WinnerDrawingDate String (YYYY-MM-DD) EntryPeriodSelector = 1 Date when winners will be drawn
WinnerDrawingTime String EntryPeriodSelector = 1 Time of drawing
WinnerDrawingTimezone String EntryPeriodSelector = 1 Timezone for drawing
WinnerNotificationDate String (YYYY-MM-DD) EntryPeriodSelector = 1 Date when winners will be notified
WinnerNotificationTime String EntryPeriodSelector = 1 Time of notification
WinnerNotificationTimezone String EntryPeriodSelector = 1 Timezone for notification
EntryPeriodItems Array EntryPeriodSelector = 2 Array of entry period objects (see structure below)
SocialMediaEntryDescription String MethodOfEntry = 3 Description of social media entry steps
OtherDescription String MethodOfEntry = 4 Description of alternative entry method
SponsorEcommerceStoreURLA String MethodOfEntry = 5 eCommerce store URL for purchase entry ($1 = 1 entry)
SponsorEcommerceStoreURLB String MethodOfEntry = 6 eCommerce store URL for purchase entry (1 order = 1 entry)
SponsorDonationsAcceptancePageURL String MethodOfEntry = 7 Donations acceptance page URL
SponsorEcommerceStoreURLC String MethodOfEntry = 8 eCommerce store URL for subscription entry
TotalNumberOfEntriesAwardedAMOE Number (>= 1) MethodOfEntry = 5, 6, 7, or 8 Entries awarded per AMOE submission
LimitOrMaxNumberOfEntriesAMOE Number (>= 1) MethodOfEntry = 5, 6, 7, or 8 Maximum AMOE entries per person
ListOfStates Array of Strings StatesAbleToParticipate = 4 Array of US state names (e.g., ["Florida", "California"])
CustomEntryPage String (min 11 chars) SweeppeaEntryPage = 2 URL of the custom entry page

Request Parameters - Optional Fields

Parameter Type Default Description
SponsorTelephone String "" Sponsor phone number
SponsorEmail String "" Sponsor email address
SponsorOfferingMultiplier Number (1|2) 2 1=Yes, 2=No. Is sponsor offering entry multipliers?
SponsorAwardingBonusEmailSocial Number (1|2) 2 1=Yes, 2=No. Bonus entries for email/social shares?
SponsorAskingToSubmitVideo Number (1|2) 2 1=Yes, 2=No. Participants submit user-generated video?
RulesLanguage String "en" Language code for the rules document

Geographic Eligibility Options (StatesAbleToParticipate)

Value Description
1 All 50 US States + DC
2 All 50 US States + DC + Puerto Rico
3 All 50 US States + DC + All US Territories
4 Select specific states (requires ListOfStates array)
5 US and Canada (excluding Quebec)
6 US, Canada (excluding Quebec) + Puerto Rico
7 US and UK
8 US and Mexico
9 Worldwide
10 US, Canada (excluding Quebec), Mexico

Request Example

When EntryPeriodSelector = 2, provide an array of entry period objects:

{
  "EntryPeriodItems": [
    {
      "data": {
        "StartDate": "2026-03-01",
        "StartTime": "09:00 AM",
        "EndDate": "2026-03-07",
        "EndTime": "11:59 PM",
        "DrawingDate": "2026-03-08",
        "WinnersDrawn": 1,
        "NotificationDate": "2026-03-09",
        "PrizeDescription": "One (1) $100 Gift Card",
        "PrizeValue": 100
      }
    },
    {
      "data": {
        "StartDate": "2026-03-08",
        "StartTime": "12:00 AM",
        "EndDate": "2026-03-14",
        "EndTime": "11:59 PM",
        "DrawingDate": "2026-03-15",
        "WinnersDrawn": 2,
        "NotificationDate": "2026-03-16",
        "PrizeDescription": "Two (2) $50 Gift Cards",
        "PrizeValue": 100
      }
    }
  ]
}

Code Examples

cURL

curl -X POST "https://api-v3.sweeppea.com/rules/createWizard" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SweepstakesToken": "YOUR_SWEEPSTAKES_TOKEN",
    "Arv": 2,
    "AlcoholSweeps": 2,
    "SweepstakesName": "Summer Giveaway 2026 Sweepstakes",
    "StartDate": "2026-03-01",
    "StartTime": "09:00 AM",
    "StartTimezone": "US/Eastern",
    "EndDate": "2026-04-01",
    "EndTime": "11:59 PM",
    "EndTimezone": "US/Eastern",
    "PrizeDescription": "One (1) $500 Visa eGift Card.",
    "PrizeIncludeTravel": false,
    "PrizeIsVehicle": false,
    "PrizeValue": 500,
    "EntryPeriodSelector": 1,
    "WinnersToDraw": 1,
    "WinnerDrawingDate": "2026-04-05",
    "WinnerDrawingTime": "10:00 AM",
    "WinnerDrawingTimezone": "US/Eastern",
    "WinnerNotificationDate": "2026-04-07",
    "WinnerNotificationTime": "10:00 AM",
    "WinnerNotificationTimezone": "US/Eastern",
    "SponsorName": "Acme Corporation",
    "SponsorAddress": "123 Main Street",
    "SponsorCity": "Miami",
    "SponsorState": "Florida",
    "SponsorZipCode": "33131",
    "SponsorTelephone": "3051234567",
    "SponsorEmail": "info@acme.com",
    "MethodOfEntry": 1,
    "MinAgeOfParticipation": 1,
    "StatesAbleToParticipate": 1,
    "PrivacyPolicyURL": "https://acme.com/privacy",
    "SweeppeaEntryPage": 1
  }'

JavaScript

const response = await fetch('https://api-v3.sweeppea.com/rules/createWizard', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SweepstakesToken: 'YOUR_SWEEPSTAKES_TOKEN',
    Arv: 2,
    AlcoholSweeps: 2,
    SweepstakesName: 'Summer Giveaway 2026 Sweepstakes',
    StartDate: '2026-03-01',
    StartTime: '09:00 AM',
    StartTimezone: 'US/Eastern',
    EndDate: '2026-04-01',
    EndTime: '11:59 PM',
    EndTimezone: 'US/Eastern',
    PrizeDescription: 'One (1) $500 Visa eGift Card.',
    PrizeIncludeTravel: false,
    PrizeIsVehicle: false,
    PrizeValue: 500,
    EntryPeriodSelector: 1,
    WinnersToDraw: 1,
    WinnerDrawingDate: '2026-04-05',
    WinnerDrawingTime: '10:00 AM',
    WinnerDrawingTimezone: 'US/Eastern',
    WinnerNotificationDate: '2026-04-07',
    WinnerNotificationTime: '10:00 AM',
    WinnerNotificationTimezone: 'US/Eastern',
    SponsorName: 'Acme Corporation',
    SponsorAddress: '123 Main Street',
    SponsorCity: 'Miami',
    SponsorState: 'Florida',
    SponsorZipCode: '33131',
    SponsorTelephone: '3051234567',
    SponsorEmail: 'info@acme.com',
    MethodOfEntry: 1,
    MinAgeOfParticipation: 1,
    StatesAbleToParticipate: 1,
    PrivacyPolicyURL: 'https://acme.com/privacy',
    SweeppeaEntryPage: 1
  })
});

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

Python

import requests
import json

url = "https://api-v3.sweeppea.com/rules/createWizard"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "SweepstakesToken": "YOUR_SWEEPSTAKES_TOKEN",
    "Arv": 2,
    "AlcoholSweeps": 2,
    "SweepstakesName": "Summer Giveaway 2026 Sweepstakes",
    "StartDate": "2026-03-01",
    "StartTime": "09:00 AM",
    "StartTimezone": "US/Eastern",
    "EndDate": "2026-04-01",
    "EndTime": "11:59 PM",
    "EndTimezone": "US/Eastern",
    "PrizeDescription": "One (1) $500 Visa eGift Card.",
    "PrizeIncludeTravel": False,
    "PrizeIsVehicle": False,
    "PrizeValue": 500,
    "EntryPeriodSelector": 1,
    "WinnersToDraw": 1,
    "WinnerDrawingDate": "2026-04-05",
    "WinnerDrawingTime": "10:00 AM",
    "WinnerDrawingTimezone": "US/Eastern",
    "WinnerNotificationDate": "2026-04-07",
    "WinnerNotificationTime": "10:00 AM",
    "WinnerNotificationTimezone": "US/Eastern",
    "SponsorName": "Acme Corporation",
    "SponsorAddress": "123 Main Street",
    "SponsorCity": "Miami",
    "SponsorState": "Florida",
    "SponsorZipCode": "33131",
    "SponsorTelephone": "3051234567",
    "SponsorEmail": "info@acme.com",
    "MethodOfEntry": 1,
    "MinAgeOfParticipation": 1,
    "StatesAbleToParticipate": 1,
    "PrivacyPolicyURL": "https://acme.com/privacy",
    "SweeppeaEntryPage": 1
}

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

Response

200 OK

{
  "Response": true,
  "Data": {
    "RulesToken": "bc225a85-c16f-4339-a1d6-d0c6d62fa18d",
    "SweepstakesToken": "1770a839-abeb-42b4-b003-888073ba1e9b",
    "Title": "SummerGiveaway-Official-Rules-02/17/2026-54321",
    "Primary": true,
    "CreationDate": "2026-02-17T12:00:00.000Z"
  },
  "Message": "Official rules created successfully via wizard."
}

400 Bad Request

Validation errors include Field, WizardStep, and Hint for easy debugging:

{
  "Response": false,
  "Message": "SweepstakesName is required. The official promotional name of the sweepstakes.",
  "Code": 400,
  "Field": "SweepstakesName",
  "WizardStep": "D",
  "Hint": "Must be between 6 and 60 characters"
}
{
  "Response": false,
  "Message": "WinnersToDraw is required when EntryPeriodSelector is 1. Number of winners to draw.",
  "Code": 400,
  "Field": "WinnersToDraw",
  "WizardStep": "H",
  "Hint": "Must be a number >= 1"
}
{
  "Response": false,
  "Message": "MethodOfEntry must be a number between 1 and 8.",
  "Code": 400,
  "Field": "MethodOfEntry",
  "WizardStep": "J",
  "Hint": "1 = Online Entry Form, 2 = Text-to-Win (SMS), 3 = Social Media, 4 = Other, 5 = Purchase + AMOE (eCommerce A), 6 = Purchase + AMOE (eCommerce B), 7 = Donation + AMOE, 8 = Purchase + AMOE (eCommerce C)"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

{
  "Response": false,
  "Message": "Sweepstakes not found. Ensure the SweepstakesToken belongs to the authenticated user.",
  "Code": 404,
  "Field": "SweepstakesToken"
}

500 Internal Server Error

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