Add Participant

Add Participant API endpoint for Sweeppea. POST participants/add. Complete documentation with code examples in cURL, JavaScript, and Python.

POST participants/add

Description

This endpoint allows you to add participants to your sweepstakes. Use this to manage your participants & groups data programmatically through the Sweeppea API.

Important Note:

Field names with multiple words (e.g., "First Name") must have spaces replaced with underscores (e.g., "First_Name")
Fields must match exactly with the Entry Page fields in the same order and structure
To obtain the correct field mapping for your sweepstakes, consult the Fetch Entry Page Fields endpoint

Request Body

Field	Type	Required	Description
`lang`	String	Yes	Language code, max 2 characters (e.g., `"EN"`)
`source`	String	Yes	Entry source, max 100 characters (e.g., `"api"`)
`sweepstakesToken`	String (UUID v4)	Yes	UUID v4 identifier of the sweepstakes
`entryPageFields`	Object	Yes	Object containing all entry page field data (see nested fields below)
`entryPageFields.KeyPhoneNumber`	String	Yes	Participant's phone number. Must be exactly 10 digits (US format, no country code, no separators).
`entryPageFields.KeyEmail`	String	Yes	Participant's email address. Length between 5 and 100 characters.
`entryPageFields.BonusEntries`	Number	No	Number of bonus entries (default: 0)
`entryPageFields.Fields`	Object	Yes	Object containing the participant's entry page field values (keys must match the Entry Page form field names exactly)

curl -X POST "https://api-v3.sweeppea.com/participants/add" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lang": "EN",
    "source": "api",
    "sweepstakesToken": "uuid-v4-string",
    "entryPageFields": {
      "KeyPhoneNumber": "5551234567",
      "KeyEmail": "john.doe@example.com",
      "BonusEntries": 0,
      "Fields": {
        "First_Name": "John",
        "Last_Name": "Doe",
        "City": "New York",
        "State": "NY"
      }
    }
  }'

const response = await fetch('https://api-v3.sweeppea.com/participants/add', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    lang: "EN",
    source: "api",
    sweepstakesToken: "uuid-v4-string",
    entryPageFields: {
      KeyPhoneNumber: "5551234567",
      KeyEmail: "john.doe@example.com",
      BonusEntries: 0,
      Fields: {
        "First_Name": "John",
        "Last_Name": "Doe",
        "City": "New York",
        "State": "NY"
      }
    }
  })
});

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

import requests

url = "https://api-v3.sweeppea.com/participants/add"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "lang": "EN",
    "source": "api",
    "sweepstakesToken": "uuid-v4-string",
    "entryPageFields": {
        "KeyPhoneNumber": "5551234567",
        "KeyEmail": "john.doe@example.com",
        "BonusEntries": 0,
        "Fields": {
            "First_Name": "John",
            "Last_Name": "Doe",
            "City": "New York",
            "State": "NY"
        }
    }
}

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

Response

200 OK

                {
  "Response": true,
  "Message": "(OK) Participant successfully added to your sweepstakes."
}
            

Error Responses

401 Unauthorized

                {
  "Response": false,
  "Message": "Invalid or Missing Bearer Token",
  "Code": 401
}
            

403 Forbidden

                {
  "Response": false,
  "Message": "Invalid API Token",
  "Code": 403
}
            

400 Bad Request

                {
  "Response": false,
  "Message": "Invalid parameters in body object, read documentation.",
  "Code": 400
}
            