Getting Your API Key

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

Then, copy your API Key.

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.	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_get_lists = "https://sweepwidgetapi.com/sw_api/users?api_key=123456789&page_start=1&competition_id=123";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url_get_lists,
    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(
        "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.	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_get_lists = "https://sweepwidgetapi.com/sw_api/winners?api_key=123456789&page_start=1&competition_id=123";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url_get_lists,
    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(
        "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.	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_get_lists = "https://sweepwidgetapi.com/sw_api/entries?api_key=123456789&page_start=1&competition_id=123";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url_get_lists,
    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(
        "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.	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_get_lists = "https://sweepwidgetapi.com/sw_api/giveaways?api_key=123456789&type=live&page_start=1";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url_get_lists,
    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(
        "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.	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?api_key=12345&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(
        "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.	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_get_lists = "https://sweepwidgetapi.com/sw_api/user-entered-giveaways?api_key=123456789&search_value=123&search_key=user_id";

// Example searching by the user's email address
$url_get_lists = "https://sweepwidgetapi.com/sw_api/user-entered-giveaways?api_key=123456789&[email protected]&search_key=user_email";

curl_setopt_array($curl, array(
    CURLOPT_URL => $url_get_lists,
    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(
        "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.	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 = [
    'api_key' => '123456789',
    'global' => 0,
    'competition_id' => '123',
    'whitelisted_emails' => array('[email protected]', '[email protected]', '[email protected]')
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/white-list-emails');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	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 = [
    'api_key' => '123456789',
    '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'
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-entry-method');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	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 = [
    'api_key' => '123456789',
    'competition_id' => '123',
    'entry_method_id' => '5',
    'entries_worth' => '20',
    'entry_method_handle' => 'Follow Us On Instagram',
    'mandatory' => '1'
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/update-entry-method');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	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 = [
    'api_key' => '123456789',
    'competition_id' => '123',
    'entry_method_id' => '5'
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/delete-entry-method');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	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 = [
    'api_key' => '123456789',
    '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'
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-giveaway');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	Required
competition_id	Integer	ID of your competition.	Required

Example Request

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

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/update-giveaway');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	Required
competition_id	Integer	ID of your competition.	Required

Example Request

$post = [
    'api_key' => '123456789',
    'competition_id' => '12345'
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/delete-giveaway');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	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 = [
    'api_key' => '123456789',
    'competition_id' => '12345',
    'prize_name' => '$100 Amazon Gift Card',
    'prize_winners_allowed' => '1',
    'prize_value' => '100.00',
    'prize_currency' => 'USD'
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-prize');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	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 = [
    'api_key' => '123456789',
    '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'
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-reward');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	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 = [
    'api_key' => '123456789',
    'competition_id' => '123',
    'entry_amount' => '1',
    'user_email' => '[email protected]'
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/add-manual-entries');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	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 = [
    'api_key' => '12345',
    '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
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidgetapi.com/sw_api/new-entry');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

$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.	Required
competition_id	Integer	ID of your competition.	Required
user_email	String	Email of the user.	Required

Example Request

$curl = curl_init();

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

curl_setopt_array($curl, array(
    CURLOPT_URL => $url_get_lists,
    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(
        "Content-Type: application/json"
    ),
));

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