Posted in: Giveaway Features

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.

If uses the following endpoint with the GET method.

https://sweepwidget.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://sweepwidget.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": "Lisa",
      "user_email": "[email protected]",
      "birthday": "04-25-1994",
      "entry_type": "Twitter Follow",
      "timestamp": "2020-06-26 11:18:21"
      "country": "United States",
      "ip": "123.456.789"
    }
  ]
}

List all entries for a giveaway

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

If uses the following endpoint with the GET method.

https://sweepwidget.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://sweepwidget.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": "Lisa",
      "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",
      "ip": "123.456.789"
    }
  ]
}

List all giveaways

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

If uses the following endpoint with the GET method.

https://sweepwidget.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://sweepwidget.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": "<div id='12345-ai3jf819' class='sw_container'></div><script type='text/javascript' src='https://sweepwidget.com/w/j/w_init.js'></script>"
    }
  ]
}

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.

If uses the following endpoint with the GET method.

https://sweepwidget.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://sweepwidget.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://sweepwidget.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.

If uses the following endpoint with the POST method.

https://sweepwidget.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://sweepwidget.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);