Fetch Participants
Fetch Participants API endpoint for Sweeppea. POST /participants/fetch. Retrieve paginated list of participants with search capabilities.
POST
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 | 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"
}'
Response
200 OK
{
"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
400 Bad Request
{
"Response": false,
"Message": "Invalid or Missing sweepstakesToken",
"Code": 400
}
404 Not Found
{
"Response": false,
"Message": "Sweepstakes Not Found or Access Denied",
"Code": 404
}
Notes
info
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
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
security
Access Control
- Participants must belong to the specified sweepstakes
- Sweepstakes must belong to the authenticated user