Count Participants

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

Description

This endpoint allows you to count participants in a sweepstakes. You can filter by participant type (participants, AMOE participants, opt-outs, or all) and apply date range filters. Use this to get statistics about your sweepstakes participants programmatically through the Sweeppea API.

Request Body Parameters

Parameter	Type	Required	Description
`SweepstakesToken`	String (UUID v4)	Yes	Unique identifier for the sweepstakes
`FilterType`	String	No	Type of count: "all", "participants", "amoe", "optouts" (default: "all")
`StartDate`	String (ISO 8601)	No	Start date for filtering participants (e.g., "2025-01-01")
`EndDate`	String (ISO 8601)	No	End date for filtering participants (e.g., "2025-12-31")

Request Body

Field	Type	Required	Description
`SweepstakesToken`	String (UUID v4)	Yes	Unique identifier for the sweepstakes
`FilterType`	String	No	Type of count: `"all"`, `"participants"`, `"amoe"`, `"optouts"` (default: `"all"`)
`StartDate`	String (ISO 8601)	No	Start date for filtering participants (e.g., `"2025-01-01"`)
`EndDate`	String (ISO 8601)	No	End date for filtering participants (e.g., `"2025-12-31"`)

Code Examples

curl -X POST "https://api-v3.sweeppea.com/participants/count" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SweepstakesToken": "uuid-v4-string",
    "FilterType": "all",
    "StartDate": "2025-01-01",
    "EndDate": "2025-12-31"
  }'

const response = await fetch('https://api-v3.sweeppea.com/participants/count', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SweepstakesToken: 'uuid-v4-string',
    FilterType: 'all',
    StartDate: '2025-01-01',
    EndDate: '2025-12-31'
  })
});

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

import requests
import json

url = "https://api-v3.sweeppea.com/participants/count"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "SweepstakesToken": "uuid-v4-string",
    "FilterType": "all",
    "StartDate": "2025-01-01",
    "EndDate": "2025-12-31"
}

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

Response

{
  "Response": true,
  "Data": {
    "SweepstakesToken": "uuid-v4-string",
    "FilterType": "all",
    "DateRange": {
      "StartDate": "2025-01-01",
      "EndDate": "2025-12-31"
    },
    "Counts": {
      "Participants": 1250,
      "AmoeParticipants": 85,
      "OptOuts": 42,
      "Total": 1377
    }
  }
}

Filter Type Examples

Count Only Participants:

{
  "SweepstakesToken": "uuid-v4-string",
  "FilterType": "participants"
}

Count Only AMOE Participants:

{
  "SweepstakesToken": "uuid-v4-string",
  "FilterType": "amoe"
}

Count Only Opt-Outs:

{
  "SweepstakesToken": "uuid-v4-string",
  "FilterType": "optouts"
}

Error Responses

{
  "Response": false,
  "Message": "Invalid or Missing SweepstakesToken",
  "Help": {
    "ExpectedBody": {
      "SweepstakesToken": "string (required) \u2014 UUID v4 of the sweepstakes",
      "FilterType": "string (optional) \u2014 which counter to filter by",
      "StartDate": "string (optional) \u2014 range start, ISO format YYYY-MM-DD",
      "EndDate": "string (optional) \u2014 range end, ISO format YYYY-MM-DD"
    }
  },
  "Code": 400
}

{
  "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": "Sweepstakes Not Found or Access Denied",
  "Code": 404
}