Add Participant

POST https://api-v3.sweeppea.com/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

Email & SMS Campaigns:

A participant created through this endpoint can receive your email and SMS campaigns. By calling it you warrant that the person registered themselves and agreed to receive marketing messages from you.
Do not use this endpoint to upload an existing contact list. Lists belong in the Participants → Tools → Import tool, whose contacts are stored and can take part in draws but are excluded from every campaign — a column in a file is not consent.
Every campaign still skips anyone who unsubscribed, replied STOP, bounced or complained.

Request Body

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

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 US or Canada phone number. Accepted formats: `"2025550100"`, `"+12025550100"` (E.164), `"(202) 555-0100"`, `"202-555-0100"`, `"12025550100"`. The value is normalized to 10 digits before it is stored. A non-`+1` country code is rejected rather than truncated.
`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)
`Consent`	Object	No	Marketing consent per channel: `{ "Email": true, "Sms": false }`. Omitted keys follow the API default (opted in, on your warranty under the AUP); an explicit `false` is always honoured and keeps that channel transactional-only for this participant. Any other key or a non-boolean value returns `400` (`PART-0018`).

Code Examples

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

{
  "Response": true,
  "Data": {
    "ParticipantToken": "uuid-v4-string"
  },
  "Message": "Participant successfully added to your sweepstakes."
}

Error Responses

{
  "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": "Invalid parameters in body object, read documentation.",
  "Code": 400
}

{
  "Response": false,
  "Telemetry": {
    "DataConsumed": 1234,
    "APICalls": 1000,
    "MaxAPICalls": 1000
  },
  "Message": "You have reached the maximum API calls allowed for this month. Contact support for more information."
}

{
  "Response": false,
  "Message": "User Not Found",
  "Code": 404
}