Create Group

Create a new group for a sweepstakes. Groups allow you to organize and segment participants within your sweepstakes.

POST https://api-v3.sweeppea.com/groups/create

Description

This endpoint allows you to create a new group for a specific sweepstakes. The group will be associated with the authenticated user and the specified sweepstakes. Use this to manage your participants & groups data programmatically through the Sweeppea API.

Request 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)	Required	The UUID token of the sweepstakes where the group will be created
`GroupName`	String	Required	The name of the group (must be unique within the sweepstakes). Maximum 100 characters; longer values are rejected with a 400.

Code Examples

curl -X POST "https://api-v3.sweeppea.com/groups/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SweepstakesToken": "uuid-v4-string",
    "GroupName": "VIP Members"
  }'

const response = await fetch('https://api-v3.sweeppea.com/groups/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SweepstakesToken: "uuid-v4-string",
    GroupName: "VIP Members"
  })
});

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

import requests

url = "https://api-v3.sweeppea.com/groups/create"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "SweepstakesToken": "uuid-v4-string",
    "GroupName": "VIP Members"
}

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

Response

{
  "Response": true,
  "Data": {
    "GroupToken": "uuid-v4-string",
    "GroupName": "VIP Members",
    "SweepstakesToken": "uuid-v4-string",
    "Primary": false,
    "Locked": false,
    "CreationDate": "2026-01-15T13:13:42.851Z"
  },
  "Message": "Group created successfully"
}

Error Responses

400 Bad Request

{  "Response": false,
  "Message": "Missing required parameters: SweepstakesToken and GroupName"
}

{
  "Response": false,
  "Message": "Group name already exists for this sweepstakes"
}

{
  "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"
}

{
  "Response": false,
  "Message": "Sweepstakes not found or does not belong to user"
}