Fetch Participants

Retrieve paginated list of participants with search capabilities.

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

Description

This endpoint allows you to fetch a paginated list of participants from a sweepstakes. Results are returned 20 per page, sorted by creation date (most recent first). The endpoint supports searching by first name, last name, email, or phone number across all collections (Participants, ParticipantsAmoe, OptOuts).

Request Body Parameters

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

Parameter	Type	Required	Description
`SweepstakesToken`	String (UUID v4)	Yes	Unique identifier for the sweepstakes
`Page`	Number	No	Page number for pagination (default: 1)
`Search`	String	No	Search term to filter by first name, last name, email, or phone number (case-insensitive)
`optInDate`	Date (YYYY-MM-DD)	No	Filter participants by specific opt-in date
`startDate`	Date (YYYY-MM-DD)	No	Filter participants from this date (requires endDate)
`endDate`	Date (YYYY-MM-DD)	No	Filter participants until this date (requires startDate)

Request Body

Field	Type	Required	Description
`SweepstakesToken`	String (UUID v4)	Yes	Unique identifier for the sweepstakes
`Page`	Number	No	Page number for pagination (default: 1)
`Search`	String	No	Search term to filter by first name, last name, email, or phone number (case-insensitive)
`optInDate`	Date (YYYY-MM-DD)	No	Filter participants by specific opt-in date
`startDate`	Date (YYYY-MM-DD)	No	Filter participants from this date (requires `endDate`)
`endDate`	Date (YYYY-MM-DD)	No	Filter participants until this date (requires `startDate`)

Code Examples

curl -X POST "https://api-v3.sweeppea.com/participants/fetch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SweepstakesToken": "uuid-v4-string",
    "Page": 1,
    "Search": "john",
    "startDate": "2025-01-01",
    "endDate": "2025-01-31"
  }'

const response = await fetch('https://api-v3.sweeppea.com/participants/fetch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SweepstakesToken: 'uuid-v4-string',
    Page: 1,
    Search: 'john',
    startDate: '2025-01-01',
    endDate: '2025-01-31'
  })
});

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

import requests
import json

url = "https://api-v3.sweeppea.com/participants/fetch"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "SweepstakesToken": "uuid-v4-string",
    "Page": 1,
    "Search": "john",
    "startDate": "2025-01-01",
    "endDate": "2025-01-31"
}

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

Response

{
  "Response": true,
  "Participants": [
    {
      "ParticipantToken": "uuid-v4-string",
      "UserToken": "uuid-v4-string",
      "SweepstakesToken": "uuid-v4-string",
      "KeyEmail": "john.doe@example.com",
      "KeyPhoneNumber": "5551234567",
      "FirstName": "John",
      "LastName": "Doe",
      "BonusEntries": 0,
      "CreationDate": "2025-06-15T10:30:00.000Z",
      "Status": true,
      "Collection": "Participants"
    },
    {
      "ParticipantToken": "uuid-v4-string",
      "UserToken": "uuid-v4-string",
      "SweepstakesToken": "uuid-v4-string",
      "KeyEmail": "jane.doe@example.com",
      "KeyPhoneNumber": "5559876543",
      "FirstName": "Jane",
      "LastName": "Doe",
      "CreationDate": "2025-06-14T15:20:00.000Z",
      "Status": true,
      "Collection": "Participants"
    }
  ],
  "Pagination": {
    "Page": 1,
    "Limit": 20,
    "Total": 45,
    "TotalPages": 3
  }
}

Fetch Without Search

{
  "SweepstakesToken": "uuid-v4-string",
  "Page": 1
}

Fetch With Search and Date Range

{
  "SweepstakesToken": "uuid-v4-string",
  "Page": 1,
  "Search": "john",
  "startDate": "2025-01-01",
  "endDate": "2025-01-31"
}

Fetch By Specific Opt-In Date

{
  "SweepstakesToken": "uuid-v4-string",
  "Page": 1,
  "optInDate": "2025-01-15"
}

Error Responses

{
  "Response": false,
  "Message": "Invalid or Missing SweepstakesToken",
  "Help": {
    "ExpectedBody": {
      "SweepstakesToken": "string (required) \u2014 UUID v4 of the sweepstakes (sweepstakesToken is also accepted)",
      "Page": "number (optional) \u2014 page number, starting at 1",
      "Search": "string (optional) \u2014 matches email or phone number",
      "OptInDate": "string (optional) \u2014 exact registration date, YYYY-MM-DD",
      "StartDate": "string (optional) \u2014 range start, YYYY-MM-DD",
      "EndDate": "string (optional) \u2014 range end, YYYY-MM-DD"
    }
  },
  "Code": 400
}

{
  "Response": false,
  "Message": "Sweepstakes Not Found or Access Denied",
  "Code": 404
}

Notes

Pagination & Results

Returns 20 participants per page
Results are sorted by CreationDate (most recent first)
Each participant includes a "Collection" field indicating its source
Each participant includes "BonusEntries" field showing bonus entries count

Search Capabilities

Searches across Participants, ParticipantsAmoe, and OptOuts collections
Search is case-insensitive and matches partial strings
Search applies to: FirstName, LastName, KeyEmail, and KeyPhoneNumber
Filter by optInDate (specific date) - uses CreationDate field
Filter by date range (startDate and endDate) - uses CreationDate field

Access Control

Participants must belong to the specified sweepstakes
Sweepstakes must belong to the authenticated user