SweepWidget API Documentation


The SweepWidget API allows you to read and write data to your giveaways. If you need any specific functionality that isn’t currently available, feel free to contact us.

How to find your API key?

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

Then, copy your API Key.

Accepted API Endpoints

The following API endpoints are accepted:

List all unique users for a giveaway

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

It uses the following endpoint with the GET method.

https://sweepwidgetapi.com/sw_api/users

Parameters

The following parameters are accepted.

Parameter Format Description Required
api_key String API developer key. Yes
competition_id Integer ID of your competition. Yes
page_start Integer The page you want to start on. JSON output returns 50 rows at a time. Yes

Example implementation

PHP example:

$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" // You must set the content-type to application/json
    ),
));

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

Example output

{
  "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 entries for a giveaway

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

It uses the following endpoint with the GET method.

https://sweepwidgetapi.com/sw_api/entries

Parameters

The following parameters are accepted.

Parameter Format Description Required
api_key String API developer key. Yes
competition_id Integer ID of your competition. Yes
page_start Integer The page you want to start on. JSON output returns 50 rows at a time. Yes

Example implementation

PHP example:

$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" // You must set the content-type to application/json
    ),
));

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

Example output

{
  "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.

It uses the following endpoint with the GET method.

https://sweepwidgetapi.com/sw_api/giveaways

Parameters

The following parameters are accepted.

Parameter Format Description Required
api_key String API developer key. Yes
type String Accepts any of the 3 values: live, scheduled, expired Yes
page_start Integer The page you want to start on. JSON output returns 50 rows at a time. Yes

Example implementation

PHP example:

$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" // You must set the content-type to application/json
    ),
));

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

Example output

{
  "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": "PGRpdiBpZD0iNjEyODctMHlwbXc3MTkiIGNsYXNzPSJzd19jb250YWluZXIiPjwvZGl2PjxzY3JpcHQgdHlwZT0idGVa4dC9qYXZhc2yaXB0IiBzcmM9Imh0dHBzOi8vc3dlZXB3aWRnZXQuY29tL3cvai93X2luaXQuanMiPjwvc2NyaXB0Pg" // <-- You have to base64_decode() this value!
    }
  ]
}

IMPORTANT! The giveaway_embed_code is outputted in base 64 encoded format (because it’s HTML). So, you have have to base 64 decode this value to get the HTML value. e.g. in PHP, the function would be base64_decode($value);

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.

It uses the following endpoint with the GET method.

https://sweepwidgetapi.com/sw_api/user-entries

Parameters

The following parameters are accepted.

Parameter Format Description Required
api_key String API developer key. Yes
competition_id
Integer  ID of your competition. Yes
user_email string This is the email address of the user who entered. Yes

Example implementation

PHP example:

<?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" // You must set the content-type to application/json
    ),
));

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

Example output


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 won’t return giveaways they entered that were created by other hosts.

It uses the following endpoint with the GET method.

https://sweepwidgetapi.com/sw_api/user-entered-giveaways

Parameters

The following parameters are accepted.

Parameter Format Description Required
api_key String API developer key. Yes
search_value String Either the user_id or user_email of the user. Either user_id or user_email value is required.
search_key String

Accepted values: user_id OR user_email

You must specify if you’re searching for a user by their id or email address.

Either user_id or user_email is required.

Example implementation

PHP example:

$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" // You must set the content-type to application/json
    ),
));

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

Example output

{
  "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.

It uses the following endpoint with the POST method.

https://sweepwidgetapi.com/sw_api/white-list-emails

Parameters

All of the following parameters are accepted.

Parameter Format Description Required
api_key String API developer key. Yes
global Boolean Specify if this is for a single giveaway or ALL giveaways in your account. Accepted values: 1 or 0. Yes
competition_id Integer ID of your competition. Required only if global is set to 0.
whitelisted_emails Array Specify which emails are allowed to enter. Yes

Example implementation

PHP example:

$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.

It uses the following endpoint with the POST method.

https://sweepwidgetapi.com/sw_api/create-entry-method

Parameters

All of the following parameters are accepted.

Parameter Format Description Required
api_key String API developer key. Yes
competition_id Integer ID of your competition. Yes
entry_order
Integer What order the entry method appears. Yes
entry_method_type
String Type of entry method. The following entry method types are available: Available entry method types. Yes
entry_method_handle
String Title for the entry method on the outside (the title before the entrant toggles the entry method open). Yes
mandatory
Integer Whether not it’s a required entry method. Yes
entries_worth
Integer How many entries the entry method is worth. Yes
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. You can reference the entry method while creating a giveaway to see which one is required. Yes
input_header
String Header string after the entrant toggles open the entry method. Yes
additional_instructions
String Optional additional instructions (Most entry methods don’t use this). No
widget_display
Integer 1 = circle icon, 2 = square look (circle icon is the default). No
icon_color
String Hex color code for icon e.g. #3b5998 No
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. No
language
String 2 character language code. Default is english: en No

Available entry method types

Use this values in the entry_method_type parameter.

  • attend_eventbrite_event
  • attend_eventbrite_venue
  • bloglovin_follow
  • discord_join_server
  • disqus_comment
  • ebay_follow
  • etsy_follow
  • etsy_item
  • facebook_group_visit
  • facebook_page_visit
  • facebook_post_visits
  • feedburner
  • feedpress
  • instagram_follow
  • instagram_like_post
  • instagram_repost
  • instagram_submit_post
  • instagram_view_post
  • instagram_visit_profile
  • linkedin_follow
  • linkedin_share
  • mixer_follow
  • myspace_follow
  • patreon_page_visit
  • pinterest_follow_board
  • pinterest_follow_user
  • pinterest_repin_pin
  • pinterest_submit_board
  • pinterest_submit_pin
  • pinterest_visit_page
  • pinterest_visit_pin
  • reddit_subscribe
  • rss
  • snapchat_follow
  • soundcloud_follow
  • soundcloud_like_song
  • soundcloud_listen_to_song
  • soundcloud_repost_song
  • soundcloud_submit_song
  • spotify_follow
  • spotify_listen_to_song
  • steam_join_group
  • telegram_join_channel
  • tiktok_comment
  • tiktok_follow
  • tiktok_like
  • tiktok_share
  • tiktok_visit
  • tiktok_watch_video
  • tumblr_follow
  • tumblr_like_post
  • twitch_follow
  • twitch_subscribe
  • twitter_follow
  • twitter_retweet
  • twitter_tweet
  • youtube_channel_subscribe
  • youtube_comment
  • youtube_like_video
  • youtube_submit_video
  • youtube_visit_channel
  • youtube_watch

Example implementation

PHP example:

$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 SweepWidgetTEST 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);

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 as already entered your contest under the email [email protected], you can manually add 1-10,000 entries for this user.

It uses the following endpoint with the POST method.

https://sweepwidget.com/sw_api/add-manual-entries

Parameters

All of the following parameters are accepted.

Parameter Format Description Required
api_key String API developer key. Yes
competition_id Integer ID of your competition. Yes
entry_amount
Integer How many entries you are giving to this user. Yes
user_email
String The email address of the user. Note: the user must already be entered into your contest. Yes

Example implementation

PHP example:

$post = [
    'api_key' => '123456789',
    'competition_id' => '123',
    'entry_amount' => '1',
    'user_email' => '[email protected]'
];

$post_string = http_build_query($post);

$ch = curl_init('https://sweepwidget.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.

It uses the following endpoint with the POST method.

https://sweepwidgetapi.com/sw_api/new-entry

Parameters

All of the following parameters are accepted

Parameter Format Description Required
api_key String API developer key. Yes
competition_id Integer ID of your competition. Yes
user_email
String Email of the user Yes
user_name
String Name of user Yes
entry_amount
Integer How many entries is this worth? Yes
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 i.e. http:// or https:// Yes
sw_share
String

This value is the share hash from the share link. You must fetch this value from the share link on your website. The GET variable will be sw-share.

Example: https://yourwebsite.com/path-to-your-giveaway?sw-share=12345-asfdjhwe. You must fetch the value of sw-share which is equal to 12345-asfdjhwe. You must then pass it to sw_share parameter. The API will know who referred this user.

You must conditionally pass this parameter only if the share hash is set in your URL.

Note: in order for this feature to work, you must create a refer a friend entry method on the giveaway you’re using the API for.

No

Example implementation

PHP example:

$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', // This should be the link where your giveaway is hosted e.g. on your website or the hosted landing.
    //'sw_share' => '8u84os-12345' // This paremter is only if the referral link is set i.e. ?sw-share=8u84os-12. You must conditionally pass this parameter on your end.
];

$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);

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

It uses the following endpoint with the GET method.

https://sweepwidgetapi.com/sw_api/fetch-user-referral-link

Parameters

All of the following parameters are accepted.

Parameter Format Description Required
api_key String API developer key. Yes
competition_id Integer ID of your competition. Yes
user_email
String Email of the user Yes

Example implementation

PHP example:

$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" // You must set the content-type to application/json
    ),
));

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