Introduction

The SweepWidget API v2 gives you full programmatic control over your giveaways. Create and manage contests, track entries and participants, pick winners, view analytics, and automate your workflow - all through a clean REST API.

All requests and responses use JSON. The API is available exclusively to Enterprise plan users.

Base URL

https://sweepwidget.com/sw_api/v2

Quick Example

Here is a simple request to list your active giveaways:

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways?status=live" \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

Every API request must include your API key. You can find your key in Dashboard > Settings > API. The API is available exclusively on the Enterprise plan.

Three authentication methods are supported (in order of preference):

MethodHow to UseExample
Bearer Token (recommended)Authorization headerAuthorization: Bearer sk_live_abc123
API Key HeaderX-API-Key headerX-API-Key: sk_live_abc123
Query Parameterapi_key in URL?api_key=sk_live_abc123
Note: Keep your API key secret. Never expose it in client-side code or public repositories. All requests must be made over HTTPS.

Rate Limits

The API enforces rate limits to ensure fair usage and stability. Write operations (POST, PUT, DELETE) count as 2 requests toward your per-minute limit.

LimitValue
Requests per minute120 (60 for write operations)
Requests per day100,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1708459200

When you exceed the limit, you will receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

Pagination

List endpoints return paginated results. Use the page and per_page query parameters to navigate through results.

JSON
{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6,
    "has_more": true
  },
  "meta": {
    "request_id": "req_7f3a9b2c1d4e"
  }
}

Errors

The API uses standard HTTP status codes. Errors include a descriptive message and, when applicable, field-level details to help you fix the issue.

CodeMeaning
400Bad Request - Invalid parameters or missing required fields
401Unauthorized - Invalid or missing API key
403Forbidden - Your plan does not have access, or you do not own this resource
404Not Found - The requested resource does not exist
422Validation Error - The request body failed validation
429Rate Limited - Too many requests. Check the Retry-After header
500Server Error - Something went wrong on our end
Error Response
{
  "success": false,
  "error": {
    "code": 422,
    "message": "Validation failed.",
    "details": {
      "title": "Title is required.",
      "end_time": "End time must be after start time."
    }
  }
}

Account

Retrieve information about your SweepWidget account, brands, and API usage.

GET /v2/account Get account details

Returns your account information including your email, current plan, the brand (website) tied to your API key, and how many giveaways you have created. Use this to verify your API key is working and to check which account it belongs to.

Response Fields

FieldTypeDescription
user_idintegerYour SweepWidget user ID
emailstringThe email address on your account
usernamestring|nullYour username, if set
planintegerPlan ID (6 or 7 = Enterprise)
plan_namestringHuman-readable plan name (e.g. "Enterprise")
payment_platformintegerPayment platform ID (1 = Stripe, 2 = Shopify, 3 = Chargebee)
website_idinteger|nullThe brand/website ID associated with this API key
website_namestring|nullThe brand/website name
total_giveawaysintegerTotal number of active (non-deleted) giveaways on your account
created_atstring|nullAccount creation timestamp

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/account" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "user_id": 4521,
    "email": "[email protected]",
    "username": "mycompany",
    "plan": 6,
    "plan_name": "Enterprise",
    "payment_platform": 1,
    "website_id": 8934,
    "website_name": "My Company",
    "total_giveaways": 47,
    "created_at": "2024-03-15 10:30:00"
  },
  "meta": { "request_id": "req_a1b2c3d4e5f6" }
}
GET /v2/account/brands List your brands

Returns all active brands (websites) under your account. Each brand has its own set of giveaways, settings, and billing plan. If you only have one brand, this returns a single-item array. The brand whose API key you are using is the one that owns giveaways created through the API.

Response Fields (per brand)

FieldTypeDescription
idintegerBrand/website ID
website_namestring|nullBrand name
planintegerPlan ID for this brand
plan_namestringHuman-readable plan name
active_brandbooleanWhether this brand is active

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/account/brands" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    {
      "id": 8934,
      "website_name": "My Company",
      "plan": 6,
      "plan_name": "Enterprise",
      "active_brand": true
    },
    {
      "id": 8935,
      "website_name": "My Other Brand",
      "plan": 6,
      "plan_name": "Enterprise",
      "active_brand": true
    }
  ],
  "meta": { "request_id": "req_b2c3d4e5f6g7" }
}
GET /v2/account/usage Check your API usage

Returns how many API requests you have made in the last 24 hours, 7 days, and 30 days. Also returns your current rate limit settings (requests per minute, requests per day, and burst limit per second) so you can monitor your usage against your limits.

Response Fields

FieldTypeDescription
requests_todayintegerNumber of API requests in the last 24 hours
requests_7dintegerNumber of API requests in the last 7 days
requests_30dintegerNumber of API requests in the last 30 days
rate_limit.rpmintegerYour requests-per-minute limit
rate_limit.rpdintegerYour requests-per-day limit
rate_limit.burstintegerYour burst requests-per-second limit

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/account/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "requests_today": 1283,
    "requests_7d": 8471,
    "requests_30d": 34219,
    "rate_limit": {
      "rpm": 120,
      "rpd": 100000,
      "burst": 20
    }
  },
  "meta": { "request_id": "req_c3d4e5f6g7h8" }
}

Giveaways

Create, update, delete, and manage your giveaways. Each giveaway has a unique ID and URL slug.

GET /v2/giveaways List all your giveaways

Returns a paginated list of all giveaways on your account. You can filter by status and sort by different fields. Deleted giveaways are excluded automatically.

Query Parameters

NameTypeRequiredDescription
statusstringFilter by status: live, scheduled, expired, draft, or all (default: all)
sortstringSort order: id_desc (default), id_asc, start_time_desc, start_time_asc, end_time_desc, end_time_asc
searchstringSearch by giveaway title or URL slug
pageintegerPage number (default: 1)
per_pageintegerResults per page (default: 20, max: 100)

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways?status=live&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    {
      "id": 54321,
      "url": "summer-giveaway-a1b2c3d4",
      "status": "live",
      "title": "Summer Giveaway 2026",
      "description": "Win amazing prizes this summer!",
      "start_time": "2026-06-01 00:00:00",
      "end_time": "2026-07-01 00:00:00",
      "time_zone": "America/New_York",
      "language": "en",
      "number_of_winners": 3,
      "image_url": "https://sweepwidget.com/images/giveaway-banner.jpg",
      "total_entries": 4218,
      "total_participants": 1893,
      "is_draft": false,
      "created_at": "2026-05-28 14:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 47,
    "total_pages": 5,
    "has_more": true
  },
  "meta": { "request_id": "req_d4e5f6g7h8i9" }
}
GET /v2/giveaways/{id} Get full giveaway details

Returns the complete details for a single giveaway, including its configuration, entry counts, settings, and security rules. Use this to inspect the full state of a giveaway before making updates.

Path Parameters

NameTypeDescription
idintegerThe giveaway ID

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "id": 54321,
    "url": "summer-giveaway-a1b2c3d4",
    "status": "live",
    "title": "Summer Giveaway 2026",
    "description": "Win amazing prizes this summer!",
    "rules": "Must be 18+. Open to US residents only.",
    "start_time": "2026-06-01 00:00:00",
    "end_time": "2026-07-01 00:00:00",
    "time_zone": "America/New_York",
    "language": "en",
    "number_of_winners": 3,
    "image_url": "https://sweepwidget.com/images/banner.jpg",
    "is_draft": false,
    "public_or_private": "public",
    "competition_type": "standard",
    "total_entries": 4218,
    "total_participants": 1893,
    "total_actions": 6542,
    "entry_method_count": 5,
    "embed_code": "<div id=\"54321-summer-giveaway-a1b2c3d4\" class=\"sw_container\"></div><script src=\"https://sweepwidget.com/w/j/w_init.js\"></script>",
    "view_url": "https://sweepwidget.com/view/54321-summer-giveaway-a1b2c3d4",
    "settings": {
      "entries_or_points": "entries",
      "if_leaderboard": true,
      "leaderboard_display_amount": 10,
      "if_unlock_rewards": false,
      "show_prizes": true,
      "show_rules_expanded": false,
      "require_captcha": false,
      "show_cookies_consent_form": false
    },
    "rules_config": {
      "age_limit": 18,
      "age_limit_type": "minimum",
      "countries_allowed": ["US"],
      "allowed_world_wide": false,
      "max_entries_per_user": 0,
      "max_total_participants": 0,
      "check_for_duplicate_ip": true,
      "security_level": 2,
      "block_vpns": true,
      "block_high_risk_email_tld": false,
      "require_email_verification": false,
      "social_login_required": false
    },
    "created_at": "2026-05-28 14:30:00"
  },
  "meta": { "request_id": "req_e5f6g7h8i9j0" }
}
POST /v2/giveaways Create a new giveaway

Creates a new giveaway with the specified settings. A default "User Details" entry method is automatically created. The giveaway is created as a draft by default - use the Publish endpoint when you are ready to go live.

Body Parameters

NameTypeRequiredDescription
titlestringRequiredGiveaway title (max 255 characters)
start_timedatetimeRequiredStart time in YYYY-MM-DD HH:MM:SS format
end_timedatetimeRequiredEnd time in YYYY-MM-DD HH:MM:SS format
descriptionstringGiveaway description (displayed to participants)
rulesstringOfficial rules text
time_zonestringTimezone string (default: America/New_York)
languagestringLanguage code (default: en)
number_of_winnersintegerHow many winners to select (default: 1)
is_draftbooleanCreate as draft (default: false). Set to true to create a draft you can publish later.
settingsobjectOptional settings: entries_or_points, if_leaderboard, show_prizes, require_captcha, etc.
rules_configobjectSecurity rules: security_level (1-3), block_vpns, countries_allowed, age_limit, etc.

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Holiday Giveaway 2026",
    "start_time": "2026-12-01 00:00:00",
    "end_time": "2026-12-25 23:59:59",
    "description": "Enter to win holiday prizes!",
    "number_of_winners": 5,
    "is_draft": true,
    "rules_config": {
      "security_level": 2,
      "block_vpns": true,
      "countries_allowed": ["US", "CA", "GB"]
    }
  }'

Response

201 Created
{
  "success": true,
  "data": {
    "id": 54322,
    "url": "holiday-giveaway-2026-e5f6g7h8",
    "status": "draft",
    "title": "Holiday Giveaway 2026",
    "start_time": "2026-12-01 00:00:00",
    "end_time": "2026-12-25 23:59:59",
    "time_zone": "America/New_York",
    "embed_code": "<div id=\"54322-holiday-giveaway-2026-e5f6g7h8\" class=\"sw_container\"></div><script src=\"https://sweepwidget.com/w/j/w_init.js\"></script>",
    "view_url": "https://sweepwidget.com/view/54322-holiday-giveaway-2026-e5f6g7h8"
  },
  "meta": { "request_id": "req_f6g7h8i9j0k1" }
}
PUT /v2/giveaways/{id} Update a giveaway

Updates an existing giveaway. Only include the fields you want to change - all other fields remain unchanged. You can update the title, dates, description, settings, and security rules in a single request.

Path Parameters

NameTypeDescription
idintegerThe giveaway ID

Body Parameters

All fields are optional. Only include what you want to change.

NameTypeDescription
titlestringGiveaway title (max 255 characters)
descriptionstringGiveaway description
rulesstringOfficial rules text
start_timedatetimeStart time (YYYY-MM-DD HH:MM:SS)
end_timedatetimeEnd time
time_zonestringTimezone (e.g. America/New_York)
languagestringLanguage code
number_of_winnersintegerNumber of winners
is_draftbooleanDraft mode on/off
public_or_privatestringpublic or private
competition_typestringstandard, etc.

Settings Object (optional)

NameTypeDescription
entries_or_pointsstringentries or points
if_leaderboardbooleanEnable leaderboard
leaderboard_display_amountintegerNumber of top participants shown on leaderboard
if_unlock_rewardsbooleanEnable milestone rewards
show_prizesbooleanShow prizes on widget
show_rules_expandedbooleanShow rules expanded by default
require_captchabooleanRequire CAPTCHA verification
show_cookies_consent_formbooleanShow cookie consent form

Rules Config Object (optional)

NameTypeDescription
security_levelintegerSecurity level: 1 (low), 2 (medium), 3 (high)
check_for_duplicate_ipbooleanBlock duplicate IP addresses
block_vpnsbooleanBlock VPN/proxy connections
block_high_risk_email_tldbooleanBlock disposable/risky email domains
require_email_verificationbooleanRequire email verification before entry
age_limitintegerAge restriction (0 = no limit)
max_entries_per_userintegerMax entries per user (0 = unlimited)
max_total_participantsintegerMax participants allowed (0 = unlimited)
countries_allowedarrayArray of country codes, e.g. ["US", "CA"]. Empty array = worldwide.

cURL Example

cURL
curl -X PUT "https://sweepwidget.com/sw_api/v2/giveaways/54321" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Summer Giveaway", "number_of_winners": 5 }'

Response

200 OK
{
  "success": true,
  "data": {
    "id": 54321,
    "message": "Giveaway updated successfully."
  },
  "meta": { "request_id": "req_g7h8i9j0k1l2" }
}
DEL /v2/giveaways/{id} Delete a giveaway

Soft-deletes a giveaway. The giveaway will no longer appear in your listings or be accessible to participants, but the data is preserved internally. This action cannot be undone via the API.

cURL Example

cURL
curl -X DELETE "https://sweepwidget.com/sw_api/v2/giveaways/54321" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

204 No Content
(empty response body)
POST /v2/giveaways/{id}/duplicate Duplicate a giveaway

Creates an exact copy of an existing giveaway as a new draft. All entry methods, prizes, rewards, design settings, and rules are copied over. Entry and participant data is not copied - the new giveaway starts fresh with zero entries.

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/duplicate" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

201 Created
{
  "success": true,
  "data": {
    "id": 54323,
    "url": "summer-giveaway-copy-i9j0k1l2",
    "status": "draft",
    "view_url": "https://sweepwidget.com/view/54323-summer-giveaway-copy-i9j0k1l2"
  },
  "meta": { "request_id": "req_h8i9j0k1l2m3" }
}
POST /v2/giveaways/{id}/publish Publish a draft giveaway

Publishes a draft giveaway, making it accessible to participants. If the start time is in the future, the giveaway status will be "scheduled". If the start time has already passed, it will immediately go "live".

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54322/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "id": 54322,
    "status": "scheduled"
  },
  "meta": { "request_id": "req_i9j0k1l2m3n4" }
}
GET /v2/giveaways/{id}/stats Get real-time statistics

Returns real-time statistics for a giveaway, including total entries, participants, page views, today's activity, and conversion rate. Entry and participant counts come from real-time counters, so they are always up to date.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "competition_id": 54321,
    "status": "live",
    "days_remaining": 12,
    "total_entries": 4218,
    "total_participants": 1893,
    "total_actions": 6542,
    "total_page_views": 15430,
    "unique_page_views": 12871,
    "entries_today": 147,
    "participants_today": 63,
    "conversion_rate": 14.71
  },
  "meta": { "request_id": "req_j0k1l2m3n4o5" }
}
GET /v2/giveaways/{id}/embed-code Get embed code and links

Returns the HTML embed code snippet, direct view link, and iframe code for a giveaway. Use the embed code to display the giveaway widget on any website, or share the direct link with participants.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/embed-code" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "competition_id": 54321,
    "embed_code": "<div id=\"54321-summer-giveaway-a1b2c3d4\" class=\"sw_container\"></div><script src=\"https://sweepwidget.com/w/j/w_init.js\"></script>",
    "direct_link": "https://sweepwidget.com/view/54321-summer-giveaway-a1b2c3d4",
    "iframe_code": "<iframe src=\"https://sweepwidget.com/view/54321-summer-giveaway-a1b2c3d4\" width=\"100%\" height=\"800\" frameborder=\"0\"></iframe>"
  },
  "meta": { "request_id": "req_k1l2m3n4o5p6" }
}

Entries

View, create, and manage individual entries within a giveaway. Each entry represents a participant completing an entry method.

GET /v2/giveaways/{id}/entries List all entries

Returns a paginated list of all entries for a giveaway. Each entry shows which participant completed which entry method and how many points they earned. You can filter by entry method, date range, or search by email.

Query Parameters

NameTypeRequiredDescription
entry_methodintegerFilter by entry method ID
is_verifiedintegerFilter by verification status: 0 or 1 (default: 1)
date_fromdateStart date filter (YYYY-MM-DD)
date_todateEnd date filter (YYYY-MM-DD)
searchstringSearch by participant email
sortstringtimestamp_desc (default), timestamp_asc, entries_desc, entries_asc
pageintegerPage number (default: 1)
per_pageintegerResults per page (default: 20, max: 100)

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/entries?per_page=5&sort=timestamp_desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    {
      "id": 892341,
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_name": "Jane Smith",
      "user_email": "[email protected]",
      "entry_method": 1,
      "entry_method_name": "User Details",
      "entry_amount": 1,
      "entry_value": null,
      "is_verified": true,
      "timestamp": "2026-06-15 09:23:41",
      "country": "US"
    },
    {
      "id": 892340,
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_name": "Jane Smith",
      "user_email": "[email protected]",
      "entry_method": 14,
      "entry_method_name": "Follow on Twitter",
      "entry_amount": 3,
      "entry_value": "@sweepwidget",
      "is_verified": true,
      "timestamp": "2026-06-15 09:23:55",
      "country": "US"
    }
  ],
  "pagination": { "page": 1, "per_page": 5, "total": 4218, "total_pages": 844, "has_more": true },
  "meta": { "request_id": "req_l2m3n4o5p6q7" }
}
GET /v2/giveaways/{id}/entries/{entry_id} Get a single entry

Returns the full details for a single entry, including the participant's name, email, which entry method they completed, and when the entry was recorded.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/entries/892341" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "id": 892341,
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_name": "Jane Smith",
    "user_email": "[email protected]",
    "entry_method": 1,
    "entry_method_name": "User Details",
    "entry_amount": 1,
    "entry_value": null,
    "is_verified": true,
    "timestamp": "2026-06-15 09:23:41",
    "country": "US"
  },
  "meta": { "request_id": "req_m3n4o5p6q7r8" }
}
POST /v2/giveaways/{id}/entries Create an entry manually

Manually creates an entry for a participant. If the participant does not already exist in this giveaway, they will be automatically created as a new user. This is useful for importing entries from external sources or granting bonus entries.

Body Parameters

NameTypeRequiredDescription
user_emailstringRequiredParticipant's email address
user_namestringRequiredParticipant's display name
entry_amountintegerRequiredNumber of entries to award (minimum: 1)

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/entries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_email": "[email protected]", "user_name": "John Doe", "entry_amount": 5 }'

Response

201 Created
{
  "success": true,
  "data": {
    "id": 892350,
    "user_id": "b2c3d4e5-f6g7-8901-bcde-f12345678901",
    "user_name": "John Doe",
    "user_email": "[email protected]",
    "entry_method": 1,
    "entry_method_name": "User Details",
    "entry_amount": 5,
    "is_verified": true,
    "is_new_user": true,
    "timestamp": "2026-06-20 14:30:00"
  },
  "meta": { "request_id": "req_n4o5p6q7r8s9" }
}
POST /v2/giveaways/{id}/entries/bulk Create multiple entries at once

Creates multiple entries in a single request. Maximum 100 entries per request. Each entry in the array needs a user email and name. New users are automatically created if they do not already exist. This is ideal for bulk imports and migrations.

Body Parameters

NameTypeRequiredDescription
entriesarrayRequiredArray of entry objects (max 100). Each must include user_email, user_name, and optionally entry_amount (default: 1).

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/entries/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      { "user_email": "[email protected]", "user_name": "Alice", "entry_amount": 1 },
      { "user_email": "[email protected]", "user_name": "Bob", "entry_amount": 3 },
      { "user_email": "[email protected]", "user_name": "Carol", "entry_amount": 1 }
    ]
  }'

Response

201 Created
{
  "success": true,
  "data": {
    "created": 3,
    "failed": 0,
    "total": 3
  },
  "meta": { "request_id": "req_o5p6q7r8s9t0" }
}
DEL /v2/giveaways/{id}/entries/{entry_id} Delete an entry

Permanently deletes a single entry and adjusts the participant's entry count accordingly. The participant's total entries in the leaderboard will be recalculated. This action cannot be undone.

cURL Example

cURL
curl -X DELETE "https://sweepwidget.com/sw_api/v2/giveaways/54321/entries/892341" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

204 No Content
(empty response body)
GET /v2/giveaways/{id}/entries/export Export all entries

Exports all entries for a giveaway as a single JSON array (not paginated). Includes participant names, emails, entry methods, and timestamps. Maximum 10,000 entries per export. Use filters to narrow down the results if needed.

Query Parameters

NameTypeRequiredDescription
entry_methodintegerFilter by entry method ID
date_fromdateStart date filter (YYYY-MM-DD)
date_todateEnd date filter (YYYY-MM-DD)

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/entries/export" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    {
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Jane Smith",
      "email": "[email protected]",
      "entry_method": 1,
      "entry_method_name": "User Details",
      "entry_amount": 1,
      "timestamp": "2026-06-15 09:23:41",
      "is_verified": true,
      "country": "US"
    }
  ],
  "meta": { "request_id": "req_p6q7r8s9t0u1" }
}

Participants

View and manage the people who have entered your giveaways. Participants are identified by a unique user ID and their email address.

GET /v2/giveaways/{id}/participants List all participants

Returns a paginated list of all participants in a giveaway, along with their total entry count. Participants are users who have completed at least the base "User Details" entry method.

Query Parameters

NameTypeRequiredDescription
sortstringtotal_entries_desc (default), total_entries_asc, name_asc
pageintegerPage number (default: 1)
per_pageintegerResults per page (default: 20, max: 100)

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/participants?sort=total_entries_desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    {
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Jane Smith",
      "email": "[email protected]",
      "country": "US",
      "birthday": null,
      "total_entries": 12
    },
    {
      "user_id": "b2c3d4e5-f6g7-8901-bcde-f12345678901",
      "name": "John Doe",
      "email": "[email protected]",
      "country": "CA",
      "birthday": "1990-05-15",
      "total_entries": 8
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 1893, "total_pages": 95, "has_more": true },
  "meta": { "request_id": "req_q7r8s9t0u1v2" }
}
GET /v2/giveaways/{id}/participants/{user_id} Get participant details

Returns full details for a single participant, including their profile information and a breakdown of every entry they have earned in this giveaway (which entry methods they completed and how many points each was worth).

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/participants/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Jane Smith",
    "email": "[email protected]",
    "country": "US",
    "birthday": null,
    "total_entries": 12,
    "entries": [
      { "id": 892341, "entry_method": 1, "entry_method_name": "User Details", "entry_amount": 1, "entry_value": null, "is_verified": true, "timestamp": "2026-06-15 09:23:41" },
      { "id": 892342, "entry_method": 14, "entry_method_name": "Follow on Twitter", "entry_amount": 3, "entry_value": "@sweepwidget", "is_verified": true, "timestamp": "2026-06-15 09:24:02" },
      { "id": 892345, "entry_method": 5, "entry_method_name": "Refer a Friend", "entry_amount": 5, "entry_value": null, "is_verified": true, "timestamp": "2026-06-16 11:15:30" }
    ]
  },
  "meta": { "request_id": "req_r8s9t0u1v2w3" }
}
GET /v2/giveaways/{id}/participants/search Search by email

Searches for a participant within a giveaway by their email address. Returns the matching participant along with all of their entries. Useful for looking up a specific person's status in the contest.

Query Parameters

NameTypeRequiredDescription
qstringRequiredEmail address to search for (exact match)

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/participants/[email protected]" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    {
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Jane Smith",
      "email": "[email protected]",
      "country": "US",
      "birthday": null,
      "total_entries": 12,
      "entries": [
        { "id": 892341, "entry_method": 1, "entry_method_name": "User Details", "entry_amount": 1, "entry_value": null, "is_verified": true, "timestamp": "2026-06-15 09:23:41" }
      ]
    }
  ],
  "meta": { "request_id": "req_s9t0u1v2w3x4" }
}
GET /v2/participants/{email}/entries Cross-giveaway entry lookup

Looks up all entries for a participant by their email address across every giveaway on your account. This is a cross-giveaway lookup, not scoped to a single giveaway. Useful for seeing a participant's full engagement history. The email is passed as a URL-encoded path parameter.

Path Parameters

NameTypeDescription
emailstringParticipant's email address (URL-encoded)

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/participants/jane%40example.com/entries" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "giveaway_id": 54321, "giveaway_title": "Summer Giveaway 2026", "entry_method": 1, "entry_method_name": "User Details", "entry_amount": 1, "timestamp": "2026-06-15 09:23:41" },
    { "giveaway_id": 54321, "giveaway_title": "Summer Giveaway 2026", "entry_method": 14, "entry_method_name": "Follow on Twitter", "entry_amount": 3, "timestamp": "2026-06-15 09:24:02" },
    { "giveaway_id": 54310, "giveaway_title": "Spring Giveaway", "entry_method": 1, "entry_method_name": "User Details", "entry_amount": 1, "timestamp": "2026-04-10 08:15:00" }
  ],
  "meta": { "request_id": "req_t0u1v2w3x4y5" }
}
GET /v2/participants/{email}/giveaways Cross-giveaway lookup

Returns all giveaways on your account that a participant (identified by email) has entered. This is a cross-giveaway lookup. Useful for identifying repeat participants and understanding cross-giveaway engagement. The email is passed as a URL-encoded path parameter.

Path Parameters

NameTypeDescription
emailstringParticipant's email address (URL-encoded)

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/participants/jane%40example.com/giveaways" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "id": 54321, "title": "Summer Giveaway 2026", "total_entries": 12 },
    { "id": 54310, "title": "Spring Giveaway", "total_entries": 5 },
    { "id": 54315, "title": "May Flash Contest", "total_entries": 3 }
  ],
  "meta": { "request_id": "req_u1v2w3x4y5z6" }
}
POST /v2/giveaways/{id}/participants/{user_id}/add-entries Add bonus entries

Awards additional bonus entries to a specific participant. The entries are added to their total count and their leaderboard position is updated accordingly. Use this to reward loyal participants or compensate for issues.

Body Parameters

NameTypeRequiredDescription
amountintegerRequiredNumber of bonus entries to add (minimum: 1)

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/participants/a1b2c3d4-e5f6-7890-abcd-ef1234567890/add-entries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10 }'

Response

200 OK
{
  "success": true,
  "data": {
    "message": "Entries added successfully.",
    "entries_added": 10,
    "total_entries": 22
  },
  "meta": { "request_id": "req_v2w3x4y5z6a7" }
}
POST /v2/giveaways/{id}/participants/{user_id}/ban Ban a participant

Bans a participant from the giveaway. Their email is added to the blacklist and all of their entries are invalidated (marked as display_winner = 5). Banned participants cannot re-enter the giveaway.

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/participants/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ban" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": { "message": "Participant banned." },
  "meta": { "request_id": "req_w3x4y5z6a7b8" }
}
POST /v2/giveaways/{id}/participants/{user_id}/unban Unban a participant

Removes a ban on a participant, restoring their entries and allowing them to participate in the giveaway again. Their email is removed from the blacklist.

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/participants/a1b2c3d4-e5f6-7890-abcd-ef1234567890/unban" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": { "message": "Participant unbanned." },
  "meta": { "request_id": "req_x4y5z6a7b8c9" }
}
POST /v2/giveaways/{id}/participants/{user_id}/disqualify Disqualify a participant

Disqualifies a participant from the giveaway. Unlike banning, their entries are not deleted but are excluded from all counts and winner selection. If they had previously won a prize, the prize is made available again.

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/participants/a1b2c3d4-e5f6-7890-abcd-ef1234567890/disqualify" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": { "message": "Participant disqualified." },
  "meta": { "request_id": "req_y5z6a7b8c9d0" }
}

Entry Methods

Entry methods are the actions participants complete to earn entries (e.g., follow on Twitter, visit a URL, refer a friend). SweepWidget supports 140+ entry method types across social media, content, commerce, and more.

GET /v2/giveaways/{id}/entry-methods List configured entry methods

Returns all entry methods currently configured on a giveaway, ordered by their display position. Each method shows its type, label, how many entries it awards, and whether it is required.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/entry-methods" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    {
      "id": 100001, "entry_id": 1, "entry_method": 1, "entry_method_name": "User Details",
      "entry_title": null, "entry_link": null, "entry_amount": 1, "required": true,
      "entry_order": 1, "entry_level": null, "icon_color": null,
      "additional_instructions": null, "daily": false, "widget_display": null
    },
    {
      "id": 100002, "entry_id": 2, "entry_method": 14, "entry_method_name": "Follow on Twitter",
      "entry_title": "Follow @mycompany", "entry_link": "https://twitter.com/mycompany",
      "entry_amount": 3, "required": false, "entry_order": 2, "entry_level": null,
      "icon_color": "#1DA1F2", "additional_instructions": null, "daily": false, "widget_display": "1"
    },
    {
      "id": 100003, "entry_id": 3, "entry_method": 5, "entry_method_name": "Refer a Friend",
      "entry_title": "Share with friends", "entry_link": null, "entry_amount": 5,
      "required": false, "entry_order": 3, "entry_level": null, "icon_color": null,
      "additional_instructions": "Share your unique link with friends!", "daily": true, "widget_display": "1"
    }
  ],
  "meta": { "request_id": "req_z6a7b8c9d0e1" }
}
GET /v2/entry-method-types Browse all 125+ available types

Returns the full catalog of available entry method types, organized by category (Twitter/X, Facebook, Instagram, YouTube, TikTok, Discord, Telegram, etc.). Use the id field from this catalog when creating new entry methods on a giveaway.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/entry-method-types" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "total_types": 127,
    "categories": {
      "twitter_x": [
        { "id": 14, "name": "Follow on Twitter", "type": "twitter" },
        { "id": 15, "name": "Retweet a Tweet", "type": "twitter" },
        { "id": 16, "name": "Like a Tweet", "type": "twitter" }
      ],
      "instagram": [
        { "id": 30, "name": "Follow on Instagram", "type": "instagram" },
        { "id": 31, "name": "Like a Post", "type": "instagram" }
      ],
      "facebook": [ ... ],
      "youtube": [ ... ],
      "tiktok": [ ... ],
      "discord": [ ... ],
      "telegram": [ ... ],
      "content": [ ... ],
      "commerce": [ ... ],
      "special": [ ... ]
    }
  },
  "meta": { "request_id": "req_a7b8c9d0e1f2" }
}
POST /v2/giveaways/{id}/entry-methods Add an entry method

Adds a new entry method to a giveaway. Use the entry method type ID from the /entry-method-types catalog. The method is automatically placed at the end of the display order.

Body Parameters

NameTypeRequiredDescription
entry_methodintegerRequiredEntry method type ID (from /entry-method-types catalog)
entry_amountintegerRequiredNumber of entries/points awarded for completing this action
entry_titlestringCustom label shown to participants (e.g., "Follow @mycompany")
entry_linkstringURL for the action (e.g., Twitter profile URL)
requiredbooleanWhether this method is mandatory (default: false)
dailybooleanAllow daily repeat entries (default: false)
additional_instructionsstringExtra instructions shown to participants
icon_colorstringCustom icon color hex code (e.g., "#1DA1F2")
widget_displaybooleanWhether to display this method on the widget (default: true)

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/entry-methods" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entry_method": 14, "entry_amount": 3, "entry_title": "Follow @mycompany", "entry_link": "https://twitter.com/mycompany" }'

Response

201 Created
{
  "success": true,
  "data": {
    "id": 100004,
    "entry_id": 4,
    "entry_method": 14,
    "entry_method_name": "Follow on Twitter",
    "entry_title": "Follow @mycompany",
    "entry_link": "https://twitter.com/mycompany",
    "entry_amount": 3,
    "required": false,
    "entry_order": 4,
    "entry_level": 1,
    "icon_color": null,
    "additional_instructions": null,
    "daily": false,
    "widget_display": true
  },
  "meta": { "request_id": "req_b8c9d0e1f2g3" }
}
PUT /v2/giveaways/{id}/entry-methods/{method_id} Update an entry method

Updates an existing entry method. You can change the label, link, point value, and other settings. The entry method type itself cannot be changed - delete and re-create if you need a different type.

Body Parameters

All fields are optional. Only include what you want to change.

NameTypeDescription
entry_amountintegerPoints awarded
entry_titlestringCustom label
entry_linkstringAction URL
requiredbooleanWhether this method is mandatory
dailybooleanAllow daily repeats
additional_instructionsstringExtra instructions shown to participants
icon_colorstringCustom icon color hex code
widget_displaybooleanWhether to display on the widget

cURL Example

cURL
curl -X PUT "https://sweepwidget.com/sw_api/v2/giveaways/54321/entry-methods/100004" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entry_amount": 5, "entry_title": "Follow us on X" }'

Response

200 OK
{
  "success": true,
  "data": { "id": 100004, "message": "Entry method updated successfully." },
  "meta": { "request_id": "req_c9d0e1f2g3h4" }
}
DEL /v2/giveaways/{id}/entry-methods/{method_id} Remove an entry method

Permanently removes an entry method from a giveaway. The default "User Details" method (type 1) cannot be deleted as it is required for every giveaway. Existing entries for this method are not affected.

cURL Example

cURL
curl -X DELETE "https://sweepwidget.com/sw_api/v2/giveaways/54321/entry-methods/100004" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

204 No Content
(empty response body)
PUT /v2/giveaways/{id}/entry-methods/reorder Change display order

Sets the display order of entry methods on the giveaway widget. Pass an array of method IDs in the order you want them displayed. Methods not included in the array will be placed at the end.

Body Parameters

NameTypeRequiredDescription
orderarrayRequiredArray of entry method IDs in the desired display order

cURL Example

cURL
curl -X PUT "https://sweepwidget.com/sw_api/v2/giveaways/54321/entry-methods/reorder" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "order": [100001, 100003, 100002] }'

Response

200 OK
{
  "success": true,
  "data": { "message": "Entry methods reordered successfully." },
  "meta": { "request_id": "req_d0e1f2g3h4i5" }
}

Winners

Pick winners randomly or manually, view selected winners, and manage winner status.

GET /v2/giveaways/{id}/winners List all winners

Returns all participants who have been selected as winners for this giveaway, including their name, email, country, and any assigned prize information.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/winners" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    {
      "entry_id": 892341,
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Jane Smith",
      "email": "[email protected]",
      "country": "US",
      "timestamp": "2026-07-01 12:00:00",
      "display_winner": 1,
      "prize_info": { "prize_name": "Grand Prize", "prize_value": "$500 Gift Card" }
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 3, "total_pages": 1, "has_more": false },
  "meta": { "request_id": "req_e1f2g3h4i5j6" }
}
POST /v2/giveaways/{id}/winners/random Randomly select winners

Randomly selects winners from the pool of eligible participants. You can set a minimum entry threshold and optionally exclude participants who have already won. If fewer eligible participants exist than the requested count, all eligible participants will be selected.

Body Parameters

NameTypeRequiredDescription
countintegerRequiredNumber of winners to select (1-100)
min_entriesintegerMinimum entries required to be eligible (default: 0)
exclude_previous_winnersbooleanSkip participants already selected as winners (default: true)

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/winners/random" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 3, "min_entries": 5, "exclude_previous_winners": true }'

Response

201 Created
{
  "success": true,
  "data": {
    "winners_selected": 3,
    "winners_requested": 3,
    "eligible_pool_size": 847,
    "winners": [
      { "user_id": "a1b2c3d4-...", "name": "Jane Smith", "email": "[email protected]", "country": "US" },
      { "user_id": "c3d4e5f6-...", "name": "Mike Johnson", "email": "[email protected]", "country": "GB" },
      { "user_id": "d4e5f6g7-...", "name": "Sarah Lee", "email": "[email protected]", "country": "CA" }
    ]
  },
  "meta": { "request_id": "req_f2g3h4i5j6k7" }
}
POST /v2/giveaways/{id}/winners/manual Manually pick a winner

Manually designates a specific participant as a winner. You can identify the participant by either their user ID or email address. The participant must have at least one entry in the giveaway and cannot already be a winner.

Body Parameters

NameTypeRequiredDescription
user_idstringParticipant's user ID (provide this OR email)
emailstringParticipant's email address (provide this OR user_id)

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/winners/manual" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

Response

201 Created
{
  "success": true,
  "data": {
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Jane Smith",
    "email": "[email protected]",
    "country": "US"
  },
  "meta": { "request_id": "req_g3h4i5j6k7l8" }
}
DEL /v2/giveaways/{id}/winners/{winner_id} Remove winner status

Removes winner status from a participant by their winning entry ID (returned from the List Winners endpoint as entry_id). The participant returns to regular status and becomes eligible for future winner selection. Their entries remain intact. If the winner had a prize assigned, the prize redemption count is decremented.

cURL Example

cURL
curl -X DELETE "https://sweepwidget.com/sw_api/v2/giveaways/54321/winners/892341" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

204 No Content
(empty response body)

Prizes

Manage the prizes for your giveaways. Each prize can have a name, value, quantity, and optional redemption codes that are emailed to winners.

GET/v2/giveaways/{id}/prizesList all prizes

Returns all active prizes for a giveaway, ordered by their display position. Archived (deleted) prizes are excluded.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/prizes" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "prize_id": 1, "prize_name": "Grand Prize - $500 Gift Card", "prize_value": "500", "prize_currency": "USD", "prize_winners_allowed": 1, "prize_winners_redeemed": 0, "prize_order": 1, "redemption_switch": false, "has_redemption_codes": false },
    { "prize_id": 2, "prize_name": "Runner Up - $50 Gift Card", "prize_value": "50", "prize_currency": "USD", "prize_winners_allowed": 5, "prize_winners_redeemed": 0, "prize_order": 2, "redemption_switch": true, "has_redemption_codes": true }
  ],
  "meta": { "request_id": "req_h4i5j6k7l8m9" }
}
POST/v2/giveaways/{id}/prizesAdd a prize

Adds a new prize to a giveaway. You can optionally configure redemption codes that will be automatically emailed to winners when they are selected.

Body Parameters

NameTypeRequiredDescription
prize_namestringRequiredPrize name (max 255 characters)
prize_winners_allowedintegerRequiredHow many winners can receive this prize
prize_valuestringPrize value (e.g., "500")
prize_currencystringCurrency code (default: USD)
redemption_switchbooleanEnable redemption codes (default: false)
redemption_codesstringNewline-separated redemption codes
redemption_instructionsstringInstructions sent with the redemption email
redemption_subjectstringSubject line for the redemption email
redemption_reply_to_emailstringReply-to email for redemption notifications
redemption_reply_to_namestringReply-to name for redemption notifications

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/prizes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prize_name": "$100 Amazon Gift Card", "prize_winners_allowed": 3, "prize_value": "100", "prize_currency": "USD" }'

Response

201 Created
{
  "success": true,
  "data": { "id": 50001, "prize_id": 3, "prize_name": "$100 Amazon Gift Card", "prize_value": "100", "prize_currency": "USD", "prize_winners_allowed": 3, "prize_order": 3, "redemption_switch": false },
  "meta": { "request_id": "req_i5j6k7l8m9n0" }
}
PUT/v2/giveaways/{id}/prizes/{prize_id}Update a prize

Updates an existing prize. Only include the fields you want to change. You can update the name, value, winner count, and redemption settings.

Body Parameters

All fields are optional. Only include what you want to change.

NameTypeDescription
prize_namestringPrize name (max 255 characters)
prize_valuestringPrize value (e.g., "500")
prize_currencystringCurrency code (e.g., "USD")
prize_winners_allowedintegerHow many winners can receive this prize
redemption_switchbooleanEnable/disable redemption codes
redemption_codesstringNewline-separated redemption codes
redemption_instructionsstringInstructions sent with the redemption email
redemption_subjectstringSubject line for the redemption email
redemption_reply_to_emailstringReply-to email address
redemption_reply_to_namestringReply-to name

cURL Example

cURL
curl -X PUT "https://sweepwidget.com/sw_api/v2/giveaways/54321/prizes/3" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prize_name": "$200 Amazon Gift Card", "prize_value": "200" }'

Response

200 OK
{ "success": true, "data": { "prize_id": 3, "message": "Prize updated successfully." }, "meta": { "request_id": "req_j6k7l8m9n0o1" } }
DEL/v2/giveaways/{id}/prizes/{prize_id}Delete a prize

Archives a prize (soft delete). The prize will no longer appear in listings or be assignable to winners, but existing winner assignments are preserved.

cURL Example

cURL
curl -X DELETE "https://sweepwidget.com/sw_api/v2/giveaways/54321/prizes/3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

204 No Content
(empty response body)

Analytics

Access detailed analytics for your giveaways, including traffic, entry breakdowns, geographic data, referral sources, and fraud detection.

GET/v2/giveaways/{id}/analytics/overviewAnalytics overview

Returns a high-level analytics summary for a giveaway, including total entries, participants, page views, conversion rate, and average entries per user. Combines real-time counters with historical page view data.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/analytics/overview" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "competition_id": 54321,
    "total_entries": 4218,
    "total_participants": 1893,
    "total_actions": 6542,
    "total_views": 15430,
    "unique_views": 12871,
    "conversion_rate": 14.71,
    "avg_entries_per_user": 2.23,
    "avg_actions_per_user": 3.46
  },
  "meta": { "request_id": "req_k7l8m9n0o1p2" }
}
GET/v2/giveaways/{id}/analytics/dailyDaily stats breakdown

Returns day-by-day analytics for a giveaway, including page views, entries, and new participants for each day. Use date filters to narrow down to a specific time period.

Query Parameters

NameTypeRequiredDescription
date_fromdateStart date (YYYY-MM-DD)
date_todateEnd date (YYYY-MM-DD)

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/analytics/daily?date_from=2026-06-01&date_to=2026-06-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "date": "2026-06-01", "total_views": 2431, "unique_views": 2102, "entries": 312, "new_participants": 187 },
    { "date": "2026-06-02", "total_views": 1893, "unique_views": 1654, "entries": 245, "new_participants": 142 },
    { "date": "2026-06-03", "total_views": 1547, "unique_views": 1321, "entries": 198, "new_participants": 118 }
  ],
  "meta": { "request_id": "req_l8m9n0o1p2q3" }
}
GET/v2/giveaways/{id}/analytics/entry-methodsEntry method performance

Shows how many entries each entry method has generated, along with percentages. Helps you understand which actions are most popular with participants.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/analytics/entry-methods" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "entry_method": 1, "entry_method_name": "User Details", "total_entries": 1893, "unique_users": 1893, "percentage": 44.9 },
    { "entry_method": 14, "entry_method_name": "Follow on Twitter", "total_entries": 1245, "unique_users": 1120, "percentage": 29.5 },
    { "entry_method": 5, "entry_method_name": "Refer a Friend", "total_entries": 1080, "unique_users": 734, "percentage": 25.6 }
  ],
  "meta": { "request_id": "req_m9n0o1p2q3r4" }
}
GET/v2/giveaways/{id}/analytics/geographyGeographic distribution

Returns participant and page view counts grouped by country, split into two separate rankings. The views_by_country array shows page view data from analytics tracking, while participants_by_country shows where actual entrants are located. Both lists are capped at the top 50 countries.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/analytics/geography" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "views_by_country": [
      { "country_code": "US", "views": 5430 },
      { "country_code": "CA", "views": 2100 },
      { "country_code": "GB", "views": 1830 }
    ],
    "participants_by_country": [
      { "country": "US", "participants": 892 },
      { "country": "CA", "participants": 312 },
      { "country": "GB", "participants": 245 }
    ]
  },
  "meta": { "request_id": "req_n0o1p2q3r4s5" }
}
GET/v2/giveaways/{id}/analytics/referralsReferral source analytics

Returns the top 20 referral traffic sources for your giveaway, ranked by visit count. Each result includes the full referrer URL and the extracted domain name. Useful for understanding which websites and links are driving the most traffic.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/analytics/referrals" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "referrer_url": "https://twitter.com/mycompany/status/123", "domain": "twitter.com", "count": 534 },
    { "referrer_url": "https://www.instagram.com/p/abc123/", "domain": "www.instagram.com", "count": 312 },
    { "referrer_url": "https://myblog.com/giveaway-post", "domain": "myblog.com", "count": 201 }
  ],
  "meta": { "request_id": "req_o1p2q3r4s5t6" }
}
GET/v2/giveaways/{id}/analytics/fraudFraud detection metrics

Returns fraud detection metrics for a giveaway. Shows how many unique IP addresses submitted multiple entries, the total number of blacklisted emails/IPs, and how many participants have been disqualified. The top_duplicate_ips array ranks the most active duplicate IPs by entry count (actual IP addresses are not exposed for privacy).

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/analytics/fraud" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "duplicate_ip_entries": 12,
    "banned_count": 8,
    "disqualified_count": 3,
    "top_duplicate_ips": [
      { "rank": 1, "entry_count": 47 },
      { "rank": 2, "entry_count": 31 },
      { "rank": 3, "entry_count": 18 }
    ]
  },
  "meta": { "request_id": "req_p2q3r4s5t6u7" }
}

Leaderboard

Retrieve the leaderboard ranking for a giveaway, showing top participants by entry count.

GET/v2/giveaways/{id}/leaderboardGet leaderboard rankings

Returns the top participants ranked by their total entry count. The number of results is controlled by the giveaway's leaderboard display amount setting (default: 10). Only available when the leaderboard feature is enabled on the giveaway.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/leaderboard" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "rank": 1, "user_id": "d4e5f6g7-...", "name": "Sarah Lee", "total_entries": 45 },
    { "rank": 2, "user_id": "a1b2c3d4-...", "name": "Jane Smith", "total_entries": 38 },
    { "rank": 3, "user_id": "c3d4e5f6-...", "name": "Mike Johnson", "total_entries": 32 }
  ],
  "meta": { "request_id": "req_q3r4s5t6u7v8" }
}

Rewards

Manage milestone-based unlock rewards. Rewards are automatically unlocked when a participant reaches a specific entry threshold (e.g., "Earn 10 entries to unlock a coupon code").

GET/v2/giveaways/{id}/rewardsList unlock rewards

Returns all milestone rewards configured for a giveaway, ordered by their display position.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/rewards" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    {
      "id": 301, "type": 2, "title": "10% Off Coupon", "entries_required": 5,
      "prize_random_or_guaranteed": 1, "coupon_if_coupon_code": 1,
      "coupon_code": "SAVE10", "coupon_directions": "Use this code at checkout.",
      "hide_progress": false, "send_email": 1, "order": 1
    },
    {
      "id": 302, "type": 1, "title": "Bonus Prize Entry", "entries_required": 15,
      "prize_random_or_guaranteed": 1, "coupon_if_coupon_code": 0,
      "coupon_code": null, "coupon_directions": null,
      "hide_progress": false, "send_email": 1, "order": 2
    }
  ],
  "meta": { "request_id": "req_r4s5t6u7v8w9" }
}
POST/v2/giveaways/{id}/rewardsCreate a reward

Creates a new milestone reward. Type 1 is a prize entry, type 2 is a coupon code. Participants automatically unlock the reward when they reach the required entry count.

Body Parameters

NameTypeRequiredDescription
typeintegerRequired1 = Prize entry, 2 = Coupon code
titlestringRequiredReward title shown to participants
entries_requiredintegerRequiredNumber of entries needed to unlock (minimum: 1)
coupon_codestringCoupon code (for type 2)
coupon_directionsstringInstructions for using the coupon
hide_progressbooleanHide the progress bar from participants (default: false)
prize_random_or_guaranteedinteger1 = guaranteed, 2 = random chance (default: 1)
coupon_if_coupon_codeinteger1 = show coupon code, 0 = hide (default: 1)
send_emailinteger1 = email reward details to participant, 0 = do not email (default: 1)
email_bodystringCustom email body HTML for the reward notification
email_subjectstringCustom subject line for the reward notification
email_reply_to_emailstringReply-to email address
email_reply_to_namestringReply-to name

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/rewards" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": 2, "title": "Free Shipping Code", "entries_required": 10, "coupon_code": "FREESHIP" }'

Response

201 Created
{
  "success": true,
  "data": { "id": 303, "competition_id": 54321, "type": 2, "title": "Free Shipping Code", "entries_required": 10, "order": 3 },
  "meta": { "request_id": "req_s5t6u7v8w9x0" }
}
PUT/v2/giveaways/{id}/rewards/{reward_id}Update a reward

Updates an existing reward. Only include the fields you want to change.

Body Parameters

All fields are optional. Only include what you want to change.

NameTypeDescription
typeinteger1 = Prize entry, 2 = Coupon code
titlestringReward title shown to participants
entries_requiredintegerNumber of entries needed to unlock
coupon_codestringCoupon code (for type 2)
coupon_directionsstringInstructions for using the coupon
hide_progressbooleanHide the progress bar
prize_random_or_guaranteedinteger1 = guaranteed, 2 = random
coupon_if_coupon_codeinteger1 = show coupon, 0 = hide
send_emailinteger1 = email notification, 0 = no email
email_bodystringCustom email body HTML
email_subjectstringCustom subject line

cURL Example

cURL
curl -X PUT "https://sweepwidget.com/sw_api/v2/giveaways/54321/rewards/303" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entries_required": 20, "coupon_code": "FREESHIP20" }'

Response

200 OK
{ "success": true, "data": { "id": 303, "message": "Reward updated successfully." }, "meta": { "request_id": "req_t6u7v8w9x0y1" } }
DEL/v2/giveaways/{id}/rewards/{reward_id}Delete a reward

Permanently deletes a reward. Participants who have already unlocked it will keep their reward, but new participants will not be able to earn it.

cURL Example

cURL
curl -X DELETE "https://sweepwidget.com/sw_api/v2/giveaways/54321/rewards/303" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

204 No Content
(empty response body)

Whitelist

Restrict giveaway entry to a pre-approved list of email addresses. Only whitelisted emails can participate when this feature is enabled.

GET/v2/giveaways/{id}/whitelistList whitelisted emails

Returns a paginated list of all whitelisted email addresses for this giveaway.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/whitelist" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "id": 1, "email": "[email protected]" },
    { "id": 2, "email": "[email protected]" }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 2 },
  "meta": { "request_id": "req_u7v8w9x0y1z2" }
}
POST/v2/giveaways/{id}/whitelistAdd emails to whitelist

Adds one or more email addresses to the whitelist. Maximum 5,000 whitelisted emails per giveaway. Invalid or empty emails are skipped.

Body Parameters

NameTypeRequiredDescription
emailsarrayRequiredArray of email strings to whitelist

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/whitelist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["[email protected]", "[email protected]"] }'

Response

201 Created
{ "success": true, "data": { "competition_id": 54321, "added": 2 }, "meta": { "request_id": "req_v8w9x0y1z2a3" } }
DEL/v2/giveaways/{id}/whitelistRemove from whitelist

Removes email addresses from the whitelist. You can either pass an array of emails to remove, or a single whitelist entry ID (from the List Whitelist endpoint). Provide one or the other.

Body Parameters

NameTypeRequiredDescription
emailsarrayArray of email strings to remove (provide this OR id)
idintegerSingle whitelist entry ID to remove (provide this OR emails)

cURL Example

cURL
curl -X DELETE "https://sweepwidget.com/sw_api/v2/giveaways/54321/whitelist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["[email protected]"] }'

Response

204 No Content
(empty response body)

Blacklist

Block specific email addresses or IP addresses from entering your giveaways.

GET/v2/giveaways/{id}/blacklistList blocked values

Returns a paginated list of all blacklisted emails and IP addresses for this giveaway.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/blacklist" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "id": 401, "value": "[email protected]" },
    { "id": 402, "value": "192.168.1.100" }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 2 },
  "meta": { "request_id": "req_w9x0y1z2a3b4" }
}
POST/v2/giveaways/{id}/blacklistAdd to blacklist

Adds one or more emails or IP addresses to the blacklist. Maximum 5,000 entries per giveaway. The system automatically detects whether each value is an email or IP address.

Body Parameters

NameTypeRequiredDescription
valuesarrayRequiredArray of email addresses or IP addresses to block

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/blacklist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "values": ["[email protected]", "10.0.0.1"] }'

Response

201 Created
{ "success": true, "data": { "competition_id": 54321, "added": 2 }, "meta": { "request_id": "req_x0y1z2a3b4c5" } }
DEL/v2/giveaways/{id}/blacklist/{ban_id}Remove from blacklist

Removes a single entry from the blacklist by its ID. Get the ID from the List Blacklist endpoint.

cURL Example

cURL
curl -X DELETE "https://sweepwidget.com/sw_api/v2/giveaways/54321/blacklist/401" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

204 No Content
(empty response body)

Referrals

View referral program statistics for giveaways that use the "Refer a Friend" entry method.

GET/v2/giveaways/{id}/referralsReferral overview

Returns summary statistics for the referral program, including total referrals, how many unique participants made referrals, and the average referrals per referrer.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/referrals" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "competition_id": 54321,
    "total_referrals": 234,
    "unique_referrers": 89,
    "avg_referrals_per_referrer": 2.63
  },
  "meta": { "request_id": "req_y1z2a3b4c5d6" }
}
GET/v2/giveaways/{id}/referrals/topTop referrers

Returns the top 50 participants ranked by how many people they have successfully referred to the giveaway. Includes their name and decrypted email address for identification.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/referrals/top" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "user_id": "d4e5f6g7-...", "name": "Sarah Lee", "email": "[email protected]", "referral_count": 18 },
    { "user_id": "a1b2c3d4-...", "name": "Jane Smith", "email": "[email protected]", "referral_count": 12 },
    { "user_id": "c3d4e5f6-...", "name": "Mike Johnson", "email": "[email protected]", "referral_count": 9 }
  ],
  "meta": { "request_id": "req_z2a3b4c5d6e7" }
}

Settings

Read and update giveaway settings for rules/security, visual design, and email notifications.

GET/v2/giveaways/{id}/rulesGet security and rules

Returns the security and eligibility rules for a giveaway, including fraud prevention settings, country restrictions, age limits, and entry caps.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/rules" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "security_level": 2,
    "check_for_duplicate_ip": true,
    "block_vpns": true,
    "block_high_risk_email_tld": false,
    "require_email_verification": false,
    "age_limit": 18,
    "age_limit_type": "minimum",
    "max_entries_per_user": 0,
    "max_total_participants": 0,
    "countries_allowed": ["US", "CA", "GB"],
    "allowed_world_wide": false,
    "social_login_required": false
  },
  "meta": { "request_id": "req_a3b4c5d6e7f8" }
}
PUT/v2/giveaways/{id}/rulesUpdate security and rules

Updates security and eligibility rules. Only include the fields you want to change. Set countries_allowed to an empty array to allow worldwide access.

Body Parameters

NameTypeDescription
security_levelintegerSecurity level: 1 (basic), 2 (standard), 3 (strict)
check_for_duplicate_ipbooleanFlag duplicate IP addresses
block_vpnsbooleanBlock VPN and proxy connections
block_high_risk_email_tldbooleanBlock high-risk email domains
require_email_verificationbooleanRequire email verification before entry
age_limitintegerAge requirement (0 = no limit)
age_limit_typestring"minimum" or "maximum" age enforcement
max_entries_per_userintegerMaximum entries per participant (0 = unlimited)
max_total_participantsintegerMaximum total participants allowed (0 = unlimited)
countries_allowedarrayArray of allowed country codes (empty = worldwide)

cURL Example

cURL
curl -X PUT "https://sweepwidget.com/sw_api/v2/giveaways/54321/rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "security_level": 3, "block_vpns": true, "require_email_verification": true }'

Response

200 OK
{ "success": true, "data": { "competition_id": 54321, "message": "Rules updated successfully." }, "meta": { "request_id": "req_b4c5d6e7f8g9" } }
GET/v2/giveaways/{id}/designGet widget design

Returns the visual design and styling settings for the giveaway widget, including colors, fonts, button styles, and custom CSS.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/design" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "title": { "font_color": "#333333", "font_size": "24" },
    "body": { "font_color": "#555555", "background_color": "#ffffff", "description_background_color": null, "font_size": null },
    "input": { "border_color": null, "border_width": null, "border_radius": null },
    "links": { "font_color": null },
    "unlock": { "font_color": null, "font_size": null },
    "form": { "font_family": "Rubik", "border_color": null, "border_width": null, "border_radius": null, "box_shadow": null, "max_width": "600" },
    "top_section": { "numbers_font_color": null, "numbers_font_size": null, "text_font_color": null, "text_font_size": null, "background_color": null },
    "buttons": { "font_color": "#ffffff", "background_color": "#4a3aff", "font_size": null, "width": null, "padding": null, "border_radius": "8", "enter_text": null },
    "display": { "hide_title": false, "hide_description": false, "hide_top_bottom_lines": false },
    "landing_page": { "background_type": null, "background_color": null },
    "entry_methods_view": null,
    "custom_css": { "enabled": false, "css": null },
    "default_css": null
  },
  "meta": { "request_id": "req_c5d6e7f8g9h0" }
}
PUT/v2/giveaways/{id}/designUpdate widget design

Updates the widget's visual design. Accepts nested objects for each design section (title, body, buttons, form, etc.). Only include the sections you want to change. Custom CSS should be provided as a plain string.

cURL Example

cURL
curl -X PUT "https://sweepwidget.com/sw_api/v2/giveaways/54321/design" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "buttons": { "background_color": "#ff6600", "border_radius": "20" } }'

Response

200 OK
{ "success": true, "data": { "competition_id": 54321, "message": "Design updated successfully." }, "meta": { "request_id": "req_d6e7f8g9h0i1" } }
GET/v2/giveaways/{id}/emailsGet email settings

Returns the email notification settings for a giveaway. Email configuration is stored in Redis and includes confirmation email templates, verification email settings, and reply-to addresses. Text fields (subject, body, custom HTML) are returned base64-decoded.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/giveaways/54321/emails" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "confirmation_email": {
      "status": 1,
      "subject": "Thanks for entering!",
      "reply_to_email": "[email protected]",
      "reply_to_name": "My Company",
      "body": null,
      "custom_html": null,
      "logo_image_url": null
    },
    "verification_email": {
      "enabled": false,
      "body": null
    }
  },
  "meta": { "request_id": "req_e7f8g9h0i1j2" }
}
PUT/v2/giveaways/{id}/emailsUpdate email settings

Updates the email notification settings. Uses the same nested structure as the GET response. Text fields (subject, body, custom_html) are base64-encoded before storage. You can also update verification email settings.

Body Parameters

NameTypeDescription
confirmation_email.statusinteger1 = enabled, 0 = disabled
confirmation_email.subjectstringEmail subject line
confirmation_email.reply_to_emailstringReply-to email address
confirmation_email.reply_to_namestringReply-to name
confirmation_email.bodystringEmail body content
confirmation_email.custom_htmlstringCustom HTML email template
confirmation_email.logo_image_urlstringLogo image URL for the email
verification_email.enabledbooleanEnable/disable verification email
verification_email.bodystringVerification email body

cURL Example

cURL
curl -X PUT "https://sweepwidget.com/sw_api/v2/giveaways/54321/emails" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "confirmation_email": { "status": 1, "subject": "You are entered!" } }'

Response

200 OK
{ "success": true, "data": { "competition_id": 54321, "message": "Email settings updated successfully." }, "meta": { "request_id": "req_f8g9h0i1j2k3" } }

Manage photo contest submissions. Review, approve, or reject participant-uploaded photos and images.

POST/v2/giveaways/{id}/gallery/{entry_id}/approveApprove a submission

Approves a photo submission for public display in the giveaway gallery. Approved photos become visible to other participants and can receive votes.

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/gallery/900001/approve" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{ "success": true, "data": { "message": "Submission approved." }, "meta": { "request_id": "req_h0i1j2k3l4m5" } }
POST/v2/giveaways/{id}/gallery/{entry_id}/rejectReject a submission

Rejects a photo submission. The photo will not be displayed in the gallery and will not be eligible for voting.

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/giveaways/54321/gallery/900002/reject" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{ "success": true, "data": { "message": "Submission rejected." }, "meta": { "request_id": "req_i1j2k3l4m5n6" } }

Webhooks

Set up webhooks to receive real-time notifications when events occur in your giveaways. Webhook payloads are signed with HMAC-SHA256 for verification.

GET/v2/webhooksList all webhooks

Returns all webhooks configured on your account, including which events each webhook is subscribed to and whether it is currently active.

cURL Example

cURL
curl "https://sweepwidget.com/sw_api/v2/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": [
    { "id": 701, "url": "https://myapp.com/webhooks/sweepwidget", "events": ["entry.created", "winner.picked", "giveaway.expired"], "active": true, "created_at": "2026-06-01 10:00:00" }
  ],
  "meta": { "request_id": "req_j2k3l4m5n6o7" }
}
POST/v2/webhooksCreate a webhook

Creates a new webhook endpoint. The signing secret is only returned once at creation time - store it securely. Use the secret to verify that incoming webhook payloads are authentic by checking the HMAC-SHA256 signature in the X-Webhook-Signature header.

Body Parameters

NameTypeRequiredDescription
urlstringRequiredYour webhook endpoint URL (must be HTTPS)
eventsarrayRequiredArray of event types to subscribe to (see list below)

Available Events

EventTriggered When
entry.createdA new entry is recorded
entry.deletedAn entry is deleted
participant.createdA new participant signs up
participant.bannedA participant is banned
participant.disqualifiedA participant is disqualified
winner.pickedA winner is selected
winner.removedA winner's status is removed
giveaway.publishedA giveaway goes live
giveaway.expiredA giveaway ends

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://myapp.com/webhooks/sweepwidget", "events": ["entry.created", "winner.picked"] }'

Response

201 Created
{
  "success": true,
  "data": {
    "id": 702,
    "url": "https://myapp.com/webhooks/sweepwidget",
    "events": ["entry.created", "winner.picked"],
    "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "active": true,
    "created_at": "2026-06-20 14:30:00"
  },
  "meta": { "request_id": "req_k3l4m5n6o7p8" }
}
Important: The secret field is only returned when the webhook is first created. Store it securely - you will need it to verify webhook signatures.
PUT/v2/webhooks/{id}Update a webhook

Updates a webhook's URL, subscribed events, or active status. The signing secret cannot be changed.

Body Parameters

NameTypeDescription
urlstringNew endpoint URL
eventsarrayNew list of subscribed events
activebooleanEnable or disable the webhook

cURL Example

cURL
curl -X PUT "https://sweepwidget.com/sw_api/v2/webhooks/702" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["entry.created", "winner.picked", "giveaway.expired"], "active": true }'

Response

200 OK
{ "success": true, "data": { "message": "Webhook updated." }, "meta": { "request_id": "req_l4m5n6o7p8q9" } }
DEL/v2/webhooks/{id}Delete a webhook

Permanently deletes a webhook. You will immediately stop receiving notifications at this endpoint.

cURL Example

cURL
curl -X DELETE "https://sweepwidget.com/sw_api/v2/webhooks/702" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

204 No Content
(empty response body)
POST/v2/webhooks/{id}/testSend a test payload

Sends a test payload to your webhook endpoint so you can verify that it is correctly receiving and processing events. The test payload contains "event": "test" and is signed with HMAC-SHA256 using your webhook secret, sent in the X-SweepWidget-Signature header. Returns the HTTP response code from your server and whether delivery succeeded (2xx status).

cURL Example

cURL
curl -X POST "https://sweepwidget.com/sw_api/v2/webhooks/701/test" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK
{
  "success": true,
  "data": {
    "webhook_id": 701,
    "url": "https://myapp.com/webhooks/sweepwidget",
    "http_code": 200,
    "success": true
  },
  "meta": { "request_id": "req_m5n6o7p8q9r0" }
}
If delivery fails, an additional error field is included with the cURL error message.