Fetch Winners

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

Description

This endpoint allows you to fetch all winners from your sweepstakes. You can paginate results and search for specific winners by email or phone number.

Important Notes:

The sweepstakes must belong to the authenticated user
Results are paginated with default 10 items per page
Search works on email and phone number fields
Winners are sorted by draw date (most recent first)
Searches across Participants, ParticipantsAmoe, and OptOuts collections
Each winner includes "BonusEntries" field showing bonus entries count

Request Body

Parameter Casing: All request parameters are PascalCase. For backward compatibility, camelCase equivalents (e.g. sweepstakesToken) are also accepted.

Field	Type	Required	Description
`SweepstakesToken`	String (UUID v4)	Yes	Unique identifier of the sweepstakes
`Page`	Number	No	Page number for pagination (default: 1)
`ItemsPerPage`	Number	No	Number of items per page (default: 10)
`Search`	String	No	Search term to filter winners by email or phone number

Code Examples

curl -X POST "https://api-v3.sweeppea.com/winners/fetch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SweepstakesToken": "uuid-v4-string",
    "Page": 1,
    "ItemsPerPage": 10,
    "Search": ""
  }'

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

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

import requests

url = "https://api-v3.sweeppea.com/winners/fetch"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "SweepstakesToken": "uuid-v4-string",
    "Page": 1,
    "ItemsPerPage": 10,
    "Search": ""
}

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

Response

{
  "Response": true,
  "Message": "2 winner(s) fetched successfully.",
  "TotalWinners": 2,
  "Winners": [
    {
      "ParticipantToken": "uuid-v4-string",
      "GroupToken": "uuid-v4-string",
      "GroupName": "Participants",
      "OptInDate": "2026-02-16T11:51:46.653Z",
      "KeyPhoneNumber": "1234567890",
      "KeyEmail": "john.doe@example.com",
      "EntryPagesFields": {
        "Email": "john.doe@example.com",
        "First_Name": "John",
        "Last_Name": "Doe",
        "Mobile_Number": "1234567890"
      },
      "BonusEntries": 0,
      "WinnerInfo": true,
      "WasNotify": false,
      "IsAmoe": false,
      "Handler": "sweepstakes-handler",
      "SweepsName": "My Sweepstakes",
      "DrawDateTime": "2026-02-16T12:28:40.000Z"
    }
  ]
}

Error Responses

{
  "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": "Invalid parameters in body object, read documentation.",
  "Help": {
    "ExpectedBody": {
      "SweepstakesToken": "string (required) \u2014 UUID v4 of the sweepstakes (sweepstakesToken is also accepted)",
      "Page": "number (optional) \u2014 page number, starting at 1",
      "ItemsPerPage": "number (optional) \u2014 page size",
      "Search": "string (optional) \u2014 filters the winners list"
    }
  },
  "Code": 400
}

{
  "Response": false,
  "Message": "Sweepstakes not found.",
  "Code": 404
}

{
  "Response": false,
  "Message": "You do not have permission to access this sweepstakes.",
  "Code": 403
}