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
• List all entries for a giveaway
• List all giveaways
• List all entries for a single user in a giveaway
• List all giveaways a user has entered
• Update whitelisted emails
• Add new entry method
• Add manual entries for a user
• Enter user into a giveaway
• Fetch referral link for a user

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.

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.

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.

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.

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.

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.

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.

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.

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

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

Fetch referral link for a user

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.

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