Getting Your API Key

First, you must get your API Key. Navigate to Integrations and click on API Access.

Then, copy your API Key.

Authentication

All API requests require authentication using your API key. Send your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

How to make requests

GET endpoints (reading data): Pass parameters as query string values in the URL.

GET https://sweepwidgetapi.com/sw_api/users?competition_id=123&page_start=1
Authorization: Bearer YOUR_API_KEY

POST endpoints (writing data): Send parameters in the request body as JSON. Set the Content-Type header to application/json.

POST https://sweepwidgetapi.com/sw_api/new-entry
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "competition_id": 123,
  "user_name": "Jane",
  "user_email": "[email protected]",
  "entry_amount": 1,
  "giveaway_link": "https://yoursite.com"
}

Quick start examples

cURL

# GET - List all users for a giveaway
curl "https://sweepwidgetapi.com/sw_api/users?competition_id=123&page_start=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

# POST - Enter a user into a giveaway
curl -X POST "https://sweepwidgetapi.com/sw_api/new-entry" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "competition_id": 123,
    "user_name": "Jane",
    "user_email": "[email protected]",
    "entry_amount": 1,
    "giveaway_link": "https://yoursite.com"
  }'

Python

import requests

API_KEY = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {API_KEY}"}

# GET - List all users for a giveaway
response = requests.get(
    "https://sweepwidgetapi.com/sw_api/users",
    params={"competition_id": 123, "page_start": 1},
    headers=headers
)
print(response.json())

# POST - Enter a user into a giveaway
response = requests.post(
    "https://sweepwidgetapi.com/sw_api/new-entry",
    json={
        "competition_id": 123,
        "user_name": "Jane",
        "user_email": "[email protected]",
        "entry_amount": 1,
        "giveaway_link": "https://yoursite.com"
    },
    headers=headers
)
print(response.json())

JavaScript (Node.js)

const API_KEY = "YOUR_API_KEY";
const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

// GET - List all users for a giveaway
const usersRes = await fetch(
  "https://sweepwidgetapi.com/sw_api/users?competition_id=123&page_start=1",
  { headers }
);
const users = await usersRes.json();

// POST - Enter a user into a giveaway
const entryRes = await fetch(
  "https://sweepwidgetapi.com/sw_api/new-entry",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      competition_id: 123,
      user_name: "Jane",
      user_email: "[email protected]",
      entry_amount: 1,
      giveaway_link: "https://yoursite.com"
    })
  }
);
const result = await entryRes.json();

API Endpoints

List all users for a giveaway

This method allows you to get each unique user that has entered a giveaway.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
page_start	Integer	The page you want to start on. JSON output returns 50 rows at a time.	Required

Example Request

$curl = curl_init();

$url = "https://sweepwidgetapi.com/sw_api/users?page_start=1&competition_id=123";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json"
    ),
));

$response = json_decode(curl_exec($curl));
var_dump($response);

Example Response

{
  "data": [
    {
      "user_id": 123,
      "user_name": "Test User",
      "user_email": "[email protected]",
      "birthday": "04-25-1994",
      "entry_type": "Twitter Follow",
      "timestamp": "2020-06-26 11:18:21",
      "country": "United States"
    }
  ]
}

List all winners for a giveaway

This method allows you to fetch all of the winners for a giveaway.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
page_start	Integer	The page you want to start on. JSON output returns 50 rows at a time.	Required

Example Request

$curl = curl_init();

$url = "https://sweepwidgetapi.com/sw_api/winners?page_start=1&competition_id=123";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json"
    ),
));

$response = json_decode(curl_exec($curl));
var_dump($response);

Example Response

{
  "data": [
    {
      "user_id": 123,
      "user_name": "Test User",
      "user_email": "[email protected]",
      "birthday": "04-25-1994",
      "country": "United States"
    }
  ]
}

List all entries for a giveaway

This method allows you to access all of the user entry information for a giveaway.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
page_start	Integer	The page you want to start on. JSON output returns 50 rows at a time.	Required

Example Request

$curl = curl_init();

$url = "https://sweepwidgetapi.com/sw_api/entries?page_start=1&competition_id=123";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json"
    ),
));

$response = json_decode(curl_exec($curl));
var_dump($response);

Example Response

{
  "data": [
    {
      "user_id": 123,
      "user_name": "Test User",
      "user_email": "[email protected]",
      "birthday": "04-25-1994",
      "entry_type": "Twitter Follow",
      "action": "Follow @SweepWidget On Twitter",
      "value": "@MyTwitter",
      "entry_amount": "5",
      "timestamp": "2020-06-26 11:18:21",
      "country": "United States"
    }
  ]
}

List all giveaways

This method allows you to access basic information about all live, scheduled, and expired giveaways.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
type	String	Accepts any of the 3 values: live, scheduled, expired	Required
page_start	Integer	The page you want to start on. JSON output returns 50 rows at a time.	Required

Example Request

$curl = curl_init();

$url = "https://sweepwidgetapi.com/sw_api/giveaways?type=live&page_start=1";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json"
    ),
));

$response = json_decode(curl_exec($curl));
var_dump($response);

Example Response

{
  "data": [
    {
      "competition_id": 123,
      "competition_url": "ahej14f9",
      "type": "Live",
      "title": "My Giveaway Title",
      "description": "This is the description of my awesome giveaway!",
      "rules": "US, CA, 18+",
      "start_time": "2020-07-28 00:00:00",
      "end_time": "2020-08-28 00:00:00",
      "time_zone": "America/Chicago",
      "number_of_winners": "5",
      "image_loc": "https://sweepwidget.com/images/my-image.jpg",
      "giveaway_embed_code": "PGRpdiBpZD0i..."
    }
  ]
}

List all entries for a single user in a giveaway

This method allows you to list all of the entries a user has completed in a single giveaway.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
user_email	String	This is the email address of the user who entered.	Required

Example Request

<?php

$curl = curl_init();

$url = "https://sweepwidgetapi.com/sw_api/user-entries?competition_id=123&[email protected]";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json"
    ),
));

$response = json_decode(curl_exec($curl));
var_dump($response);

Example Response

array(4) {
  [0]=>
  object(stdClass)#2 (5) {
    ["entry_type"]=>
    string(12) "User Details"
    ["action"]=>
    string(5) "Login"
    ["value"]=>
    string(13) "Auto Verified"
    ["entry_amount"]=>
    int(1)
    ["timestamp"]=>
    string(19) "2024-02-29 15:13:51"
  }
  [1]=>
  object(stdClass)#3 (5) {
    ["entry_type"]=>
    string(19) "Facebook Page Visit"
    ["action"]=>
    string(4) "NULL"
    ["value"]=>
    string(13) "Auto Verified"
    ["entry_amount"]=>
    int(1)
    ["timestamp"]=>
    string(19) "2024-03-01 19:44:52"
  }
  [2]=>
  object(stdClass)#4 (5) {
    ["entry_type"]=>
    string(16) "Instagram Follow"
    ["action"]=>
    string(4) "NULL"
    ["value"]=>
    string(4) "Test"
    ["entry_amount"]=>
    int(1)
    ["timestamp"]=>
    string(19) "2024-03-01 19:44:58"
  }
  [3]=>
  object(stdClass)#5 (5) {
    ["entry_type"]=>
    string(15) "Email Subscribe"
    ["action"]=>
    string(4) "NULL"
    ["value"]=>
    string(13) "Auto Verified"
    ["entry_amount"]=>
    int(1)
    ["timestamp"]=>
    string(19) "2024-03-04 19:07:05"
  }
}

List all giveaways a user has entered

This method allows you to list every giveaway a user has entered. It returns the competition_id for every giveaway they entered that you created. Note: it will not return giveaways they entered that were created by other hosts.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
search_value	String	Either the user_id or user_email of the user.	Required
search_key	String	Accepted values: user_id or user_email. You must specify if you are searching for a user by their id or email address.	Required

Example Request

$curl = curl_init();

// Example searching by the user's id
$url = "https://sweepwidgetapi.com/sw_api/user-entered-giveaways?search_value=123&search_key=user_id";

// Example searching by the user's email address
$url = "https://sweepwidgetapi.com/sw_api/[email protected]&search_key=user_email";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json"
    ),
));

$response = json_decode(curl_exec($curl));
var_dump($response);

Example Response

{
  "competition_id": [
    {
    [0]=>
    string(5) "20234"
    [1]=>
    string(5) "20165"
    [2]=>
    string(5) "20137"
    [3]=>
    string(5) "20108"
    ]
  }
}

Update whitelisted emails

This method allows you update the whitelisted emails for a single competition. You can optionally update the globally whitelisted emails for all competitions.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
global	Boolean	Specify if this is for a single giveaway or ALL giveaways in your account. Accepted values: 1 or 0.	Required
competition_id	Integer	ID of your competition.	If global = 0
whitelisted_emails	Array	Specify which emails are allowed to enter.	Required

Example Request

$post = json_encode([
    'global' => 0,
    'competition_id' => '123',
    'whitelisted_emails' => array('[email protected]', '[email protected]', '[email protected]')
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/white-list-emails');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Add new entry method

This method allows you to add a new entry method to an existing giveaway.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
entry_order	Integer	What order the entry method appears.	Required
entry_method_type	String	Type of entry method. See available entry method types below.	Required
entry_method_handle	String	Title for the entry method on the outside (the title before the entrant toggles the entry method open).	Required
mandatory	Integer	Whether or not it is a required entry method.	Required
entries_worth	Integer	How many entries the entry method is worth.	Required
entry_link	String	This is either the profile handle or link depending on which one is required. Example: Instagram only requires the profile handle while Facebook requires the full link.	Required
input_header	String	Header string after the entrant toggles open the entry method.	Required
additional_instructions	String	Optional additional instructions (most entry methods do not use this).	Optional
widget_display	Integer	1 = circle icon, 2 = square look (circle icon is the default).	Optional
icon_color	String	Hex color code for icon e.g. #3b5998	Optional
require_verification	Integer	If you require the user to verify the username they performed the entry method with e.g. user must enter their Instagram username after following you.	Optional
language	String	2 character language code. Default is english: en	Optional

Available entry method types

Use these values in the entry_method_type parameter.

Example Request

$post = json_encode([
    'competition_id' => '123',
    'entry_order' => '5',
    'entry_method_type' => 'facebook_page_visit',
    'entry_method_handle' => 'Visit Us On Facebook',
    'mandatory' => '0',
    'entries_worth' => '10',
    'entry_link' => 'https://facebook.com/SweepWidget',
    'input_header' => 'Visit and follow SweepWidget on Facebook by manually clicking on the button below.',
    'additional_instructions' => '',
    'widget_display' => '1',
    'icon_color' => '#3b5998',
    'require_verification' => '1',
    'language' => 'en'
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-entry-method');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Update an entry method

This method allows you to update an existing entry method on a giveaway. Only the fields you include in the request will be updated – all other fields remain unchanged.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
entry_method_id	Integer	The entry_id of the entry method to update. You can find this from the entry method list or the response when creating an entry method.	Required
entries_worth	Integer	How many entries the entry method is worth.	Optional
entry_method_handle	String	Title for the entry method (the text shown before the entrant opens it).	Optional
entry_link	String	Profile handle or link for the entry method.	Optional
entry_title	String	Internal title/label for the entry method.	Optional
mandatory	Integer	Whether it is a required entry method. 1 = required, 0 = optional.	Optional
daily	String	0 = one-time, 1 = daily repeat.	Optional
additional_instructions	String	Additional instructions shown to the entrant.	Optional
icon_color	String	Hex color code for the icon, e.g. #3b5998.	Optional
widget_display	Integer	1 = circle icon (default), 2 = square look.	Optional
require_verification	Integer	1 = require username verification, 0 = no verification.	Optional
entry_textarea	String	Content field (tweet text, questions, purchase config, etc.).	Optional
input_options_1 through input_options_6	String	Entry method-specific options. Usage varies by type.	Optional
timer	Integer	Countdown seconds before the user can submit.	Optional
entry_order	Integer	Display order of the entry method.	Optional
entry_level	Integer	1 = pre-entry/required, 2 = bonus action.	Optional
tags	String	Entry method tags.	Optional
email_integration	String	Email provider integration config.	Optional

Example Request

$post = json_encode([
    'competition_id' => '123',
    'entry_method_id' => '5',
    'entries_worth' => '20',
    'entry_method_handle' => 'Follow Us On Instagram',
    'mandatory' => '1'
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/update-entry-method');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Example Response

{
  "message": "Successfully updated entry method 5 for competition id: 123"
}

Delete an entry method

This method allows you to delete an entry method from an existing giveaway. Note: you cannot delete the User Details (login) entry method.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
entry_method_id	Integer	The entry_id of the entry method to delete.	Required

Example Request

$post = json_encode([
    'competition_id' => '123',
    'entry_method_id' => '5'
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/delete-entry-method');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Example Response

{
  "message": "Successfully deleted entry method 5 from competition id: 123"
}

Create a giveaway

This method allows you to create a new giveaway. It creates the giveaway with all settings including design/styling, security rules, and a default User Details entry method. After creation, you can add additional entry methods, prizes, and rewards using the other API endpoints.

Required Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
title	String	Giveaway title (max 500 characters).	Required
start_time	String	Start date/time in YYYY-MM-DD HH:MM:SS format.	Required
end_time	String	End date/time in YYYY-MM-DD HH:MM:SS format. Must be after start_time.	Required

Basic Settings (optional)

Parameter	Type	Default	Description
time_zone	String	America/New_York	PHP timezone identifier (e.g. America/Chicago, Europe/London).
description	String	(empty)	HTML description of the giveaway.
rules	String	(empty)	HTML rules/terms for the giveaway.
number_of_winners	Integer	1	Number of winners (1-1000).
language	String	en	2-character language code.
is_draft	Integer	0	1 = save as draft, 0 = publish.
public_or_private	String	public	public or private.
competition_type	String	standard	standard or photo_contest.
redirect_url	String	(empty)	Post-entry redirect URL.

Entry/Points System (optional)

Parameter	Type	Default	Description
entries_or_points	Integer	1	1 = entries, 2 = points.
entries_or_points_custom_singular	String	(empty)	Custom singular label (e.g. “Token”).
entries_or_points_custom_plural	String	(empty)	Custom plural label (e.g. “Tokens”).
user_details_entries_worth	Integer	1	Entries awarded for completing the login form.
show_prizes	Integer	1	Show prizes section (0/1).
show_rules_expanded	Integer	0	Auto-expand rules section (0/1).
hide_entries_if_logged_out	Integer	0	Hide entry methods until user logs in (0/1).

Leaderboard (optional)

Parameter	Type	Default	Description
if_leaderboard	Integer	0	Enable leaderboard (0/1).
leaderboard_title	String	(empty)	Leaderboard title.
leaderboard_description	String	(empty)	Leaderboard description.
leaderboard_display_amount	Integer	10	Number of leaders to show (max 500).
leaderboard_name_display	Integer	1	1 = full name, 2 = first initial + last, 3 = first + last initial, 4 = hide.

Login Fields (optional)

Parameter	Type	Default	Description
required_main_login_options	String	1,1,0	CSV: name,email,phone (1 = required, 0 = not required).
social_login_require	Integer	0	Require social login (0/1).
social_login_options	String	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0	CSV of 15 toggles: Facebook, Twitter, Instagram, Pinterest, Google, LinkedIn, Twitch, Discord, Steam, Yahoo, Tumblr, OpenID, Telegram, Reddit, Spotify.
require_entry_method_before_login	Integer	0	Show entry methods before login form (0/1).

Security (optional)

Parameter	Type	Default	Description
security_level	Integer	1	1 = weak, 2 = standard, 3 = strong, 4 = strict.
require_captcha	Integer	1	1 = no captcha, 2 = always show, 3 = auto.
check_for_duplicate_ip	Integer	0	Block duplicate IP addresses (0/1).
block_vpns	Integer	0	Block VPN users (0/1).
block_high_risk_email_tld	Integer	1	Block disposable email addresses (0/1).
age_limit	Integer	0	0 = no limit, otherwise the age requirement.
age_limit_min_or_max	Integer	1	1 = minimum age, 2 = maximum age.
countries_allowed	String	Worldwide	Comma-separated country codes or “Worldwide”.
countries_allowed_include_or_exclude	String	include	include or exclude.
max_allowed_users_to_enter	Integer	0	Max participants (0 = unlimited).
max_allowed_entries	Integer	0	Max total entries across all users (0 = unlimited).
entries_allowed_per_user	Integer	0	Max entries per user (0 = unlimited).
require_verify_email	Integer	0	Require email verification (0/1).
if_enter_whitelist	Integer	0	Enable email whitelist (0/1).

Design/Styling (optional)

All color values are 6-character hex codes without the # symbol (e.g. 333333).

Parameter	Type	Default	Description
widget_position	Integer	2	1 = left, 2 = center, 3 = right.
title_font_color	String	333333	Title text color.
title_font_size	Integer	24	Title font size in px.
body_font_color	String	555555	Body text color.
body_background_color	String	ffffff	Body background color.
body_font_size	Integer	14	Body font size in px.
buttons_font_color	String	ffffff	Button text color.
buttons_background_color	String	2196F3	Button background color.
buttons_font_size	Integer	14	Button font size in px.
buttons_border_radius	Integer	5	Button border radius in px.
buttons_enter_text	String	(empty)	Custom button text.
form_border_color	String	e0e0e0	Form border color.
form_border_width	Integer	1	Form border width in px.
form_border_radius	Integer	5	Form border radius in px.
form_box_shadow	Integer	1	Enable form box shadow (0/1).
form_max_width	Integer	0	Max form width in px (0 = auto).
form_font_family	String	(empty)	CSS font family.
top_background_color	String	333333	Countdown bar background color.
top_numbers_font_color	String	ffffff	Countdown numbers color.
top_text_font_color	String	cccccc	Countdown text color.
input_border_color	String	cccccc	Input field border color.
input_border_radius	Integer	5	Input field border radius in px.
links_font_color	String	2196F3	Link text color.
landing_page_background_color	String	f5f5f5	Landing page background color.
entry_methods_view	Integer	1	1 = modern view, 2 = classic view.
hide_title	Integer	0	Hide the giveaway title (0/1).
hide_description	Integer	0	Hide the description (0/1).
if_custom_css	Integer	0	Enable custom CSS (0/1).
custom_css	String	(empty)	Custom CSS code.

Photo Contest Fields (optional, only when competition_type = photo_contest)

Parameter	Type	Default	Description
gallery_title	String	(empty)	Gallery section title.
gallery_description	String	(empty)	Gallery description HTML.
gallery_how_winners_determined	Integer	1	1 = user voting, 2 = admin picks.
gallery_votes_per_user	Integer	1	Number of votes per user.
gallery_require_login_to_vote	Integer	1	Require login to vote (0/1).
require_media_approval	Integer	0	Require admin approval for submissions (0/1).
gallery_button_photographer_text	String	(empty)	Custom photographer button text.
gallery_button_voter_text	String	(empty)	Custom voter button text.

Example Request

$post = json_encode([
    'title' => 'Summer Giveaway 2026',
    'start_time' => '2026-03-01 00:00:00',
    'end_time' => '2026-03-31 23:59:59',
    'time_zone' => 'America/New_York',
    'description' => 'Enter to win amazing prizes this summer!',
    'number_of_winners' => '3',
    'language' => 'en',
    'buttons_background_color' => '4CAF50',
    'title_font_color' => '222222'
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-giveaway');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Example Response

{
  "message": "Successfully created giveaway.",
  "competition_id": 12345,
  "competition_url": "a1b2c3d4",
  "giveaway_link": "https://sweepwidget.com/view/12345-a1b2c3d4",
  "embed_code": "<div id=\"12345-a1b2c3d4\" class=\"sw_container\"></div><script type=\"text/javascript\" src=\"https://sweepwidget.com/w/j/w_init.js\"></script>"
}

Update a giveaway

This method allows you to update an existing giveaway. Only the fields you include in the request will be updated – all other settings remain unchanged. You can update settings across the main giveaway, security/rules, and design/styling.

Parameters

The following parameters are required. All other parameters from the Create a giveaway endpoint are accepted as optional – only fields you include will be updated.

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required

Example Request

$post = json_encode([
    'competition_id' => '12345',
    'title' => 'Updated Giveaway Title',
    'end_time' => '2026-04-15 23:59:59',
    'buttons_background_color' => 'FF5722'
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/update-giveaway');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Example Response

{
  "message": "Successfully updated giveaway 12345."
}

Delete a giveaway

This method allows you to delete a giveaway. The giveaway is soft-deleted (it can be recovered by contacting support).

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required

Example Request

$post = json_encode([
    'competition_id' => '12345'
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/delete-giveaway');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Example Response

{
  "message": "Successfully deleted giveaway 12345."
}

Add a prize to a giveaway

This method allows you to add a prize to an existing giveaway. After adding a prize, the giveaway’s total number of winners is automatically updated to match the sum of all prize winner counts.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
prize_name	String	Name of the prize.	Required
prize_winners_allowed	Integer	Number of winners for this prize. Default: 1.	Optional
prize_value	String	Monetary value of the prize (e.g. “50.00”).	Optional
prize_currency	String	3-character currency code. Default: USD.	Optional
redemption_switch	Integer	Enable redemption codes for winners (0/1). Default: 0.	Optional
redemption_codes	String	Comma-separated redemption codes for winners.	Optional
redemption_instructions	String	HTML instructions shown to winners.	Optional
redemption_subject	String	Email subject line for winner notification.	Optional
redemption_reply_to_email	String	Reply-to email address for winner notification.	Optional
redemption_reply_to_name	String	Reply-to name for winner notification.	Optional

Example Request

$post = json_encode([
    'competition_id' => '12345',
    'prize_name' => '$100 Amazon Gift Card',
    'prize_winners_allowed' => '1',
    'prize_value' => '100.00',
    'prize_currency' => 'USD'
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-prize');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Example Response

{
  "message": "Successfully added prize to competition id: 12345",
  "prize_id": 1,
  "prize_order": 1
}

Add an unlock reward to a giveaway

This method allows you to add an unlock reward (milestone reward or instant coupon) to a giveaway. When a user earns enough entries, they automatically unlock the reward. Adding a reward automatically enables the unlock rewards feature on the giveaway.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
unlock_rewards_type	Integer	1 = prize draw entry, 2 = coupon.	Required
unlock_rewards_title	String	Name/title of the reward.	Required
unlock_rewards_entries_required	Integer	Number of entries the user must earn to unlock this reward.	Required
unlock_rewards_hide_progress	Integer	Hide the progress bar from users (0/1). Default: 0.	Optional
unlock_rewards_prize_random_or_guaranteed	Integer	1 = random drawing, 2 = guaranteed. Default: 1. Coupons are always guaranteed.	Optional
unlock_rewards_coupon_code	String	Coupon code(s), comma-separated for multiple codes.	Optional
unlock_rewards_coupon_directions	String	HTML instructions for redeeming the coupon.	Optional
unlock_rewards_if_send_email	Integer	1 = no email, 2 = default email, 3 = custom email. Default: 1.	Optional
unlock_rewards_user_email_subject	String	Custom email subject line. Supports [NAME_OF_COUPON] placeholder.	Optional
unlock_rewards_user_email_body	String	Custom email body HTML.	Optional
unlock_rewards_user_email_reply_to_email	String	Reply-to email. Default: [email protected].	Optional
unlock_rewards_user_email_reply_to_name	String	Reply-to name. Default: SweepWidget.	Optional

Example Request

$post = json_encode([
    'competition_id' => '12345',
    'unlock_rewards_type' => '2',
    'unlock_rewards_title' => '10% Off Coupon',
    'unlock_rewards_entries_required' => '5',
    'unlock_rewards_coupon_code' => 'SAVE10',
    'unlock_rewards_coupon_directions' => 'Use code SAVE10 at checkout.',
    'unlock_rewards_if_send_email' => '2'
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-reward');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Example Response

{
  "message": "Successfully added reward to competition id: 12345",
  "unlock_rewards_id": 1,
  "unlock_rewards_order": 1
}

Add manual entries for a user

This method allows you to add manual entries for a user. The user must already be entered into your giveaway to add entries. For example, if there is a user who has already entered your contest under the email [email protected], you can manually add 1-10,000 entries for this user.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
entry_amount	Integer	How many entries you are giving to this user.	Required
user_email	String	The email address of the user. Note: the user must already be entered into your contest.	Required

Example Request

$post = json_encode([
    'competition_id' => '123',
    'entry_amount' => '1',
    'user_email' => '[email protected]'
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/add-manual-entries');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Enter user into a giveaway

This method allows you to enter a user into your giveaway using the API.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
user_email	String	Email of the user.	Required
user_name	String	Name of the user.	Required
entry_amount	Integer	How many entries is this worth?	Required
giveaway_link	String	Full URL to where the giveaway is located. Example: https://yoursite.com/path-to-your-giveaway. Note: you must include the website protocol (http:// or https://).	Required
sw_share	String	The share hash from the referral link. Fetch this value from the sw-share GET variable in your URL. Example: if the URL is https://yourwebsite.com/giveaway?sw-share=12345-asfdjhwe, pass 12345-asfdjhwe as the value. Only pass this parameter when the share hash is present in the URL. Note: a refer a friend entry method must exist on the giveaway for referral tracking to work.	Optional

Example Request

$curl = curl_init();

$post = json_encode([
    'competition_id' => '123',
    'user_email' => '[email protected]',
    'user_name' => 'Test User',
    'entry_amount' => '1',
    'giveaway_link' => 'https://example.com/path-to-my-giveaway',
    //'sw_share' => '8u84os-12345' // Only pass if the referral link is set
]);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/new-entry');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

Fetch referral link for a user

This method allows you to fetch a user’s referral link for any giveaway.

Parameters

Parameter	Type	Description	Required
api_key	String	API developer key. Can also be sent as Authorization: Bearer header.	Required
competition_id	Integer	ID of your competition.	Required
user_email	String	Email of the user.	Required

Example Request

$curl = curl_init();

$url = "https://sweepwidgetapi.com/sw_api/fetch-user-referral-link?competition_id=123&[email protected]";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json"
    ),
));

$response = json_decode(curl_exec($curl));
var_dump($response);