Draw Winners
Draw Winners API endpoint for Sweeppea. POST winners/draw. Complete documentation with code examples in cURL, JavaScript, and Python.
POST
winners/draw
Description
This endpoint allows you to draw winners from your sweepstakes using a weighted random selection algorithm. The algorithm ensures fair distribution while giving participants with more bonus entries a proportionally higher chance of winning.
warning
Important Notes:
- The sweepstakes must belong to the authenticated user
- The sweepstakes cannot be paused or archived
- At least one participant must be available who hasn't won yet
- Winners are marked with the sweepstakes handler automatically
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
sweepstakesToken |
String (UUID v4) | Yes | Unique identifier of the sweepstakes |
howManyWinnersToPick |
Number | No | Number of winners to select (default: 1) |
group |
String | No | Group token to limit the draw to a specific group, or "allgroups" to include all participants (default: "allgroups") |
completedEntries |
Boolean | No | Only include participants who completed all bonus entry steps (default: false) |
includeOptedOutParticipants |
Boolean | No | Include participants who opted out of notifications (default: false) |
doNotIncludeSpamParticipants |
Boolean | No | Exclude participants flagged as spam (default: false) |
Code Examples
curl -X POST "https://api-v3.sweeppea.com/winners/draw" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sweepstakesToken": "uuid-v4-string",
"howManyWinnersToPick": 1,
"group": "allgroups",
"completedEntries": false,
"includeOptedOutParticipants": false,
"doNotIncludeSpamParticipants": true
}'
Response
200 OK
{
"Response": true,
"Message": "1 winner(s) were selected successfully.",
"Winners": [
{
"ParticipantToken": "uuid-v4-string",
"FirstName": "John",
"LastName": "Doe",
"Email": "john.doe@example.com",
"PhoneNumber": "1234567890"
}
]
}
Error Responses
401 Unauthorized
{
"Response": false,
"Message": "Invalid or Missing Bearer Token",
"Code": 401
}
403 Forbidden
{
"Response": false,
"Message": "Invalid API Token",
"Code": 403
}
400 Bad Request
{
"Response": false,
"Message": "Invalid parameters in body object, read documentation.",
"Code": 400
}
404 Not Found
{
"Response": false,
"Message": "Sweepstakes not found.",
"Code": 404
}
403 Forbidden
{
"Response": false,
"Message": "You do not have permission to access this sweepstakes.",
"Code": 403
}
400 Bad Request
{
"Response": false,
"Message": "Cannot draw winners from a paused sweepstakes.",
"Code": 400
}
400 Bad Request
{
"Response": false,
"Message": "Cannot draw winners from an archived sweepstakes.",
"Code": 400
}
400 Bad Request
{
"Response": false,
"Message": "No participants available to draw winners.",
"Code": 400
}