SweepWidget API Documentation


The SweepWidget API allows you to read and write data to your giveaways. If you need any specific functionality that is not currently available, feel free to contact support.

Plan: The API is available on the Enterprise plan only. On other plans the API key is hidden and every call returns {"message":"API access not allowed."}.

Base URL https://sweepwidgetapi.com/sw_api/

Getting Your API Key

  1. Click Integrations in the left sidebar.
  2. Click the SweepWidget API card.
  3. Copy the key in the API Key field.

Each brand has its own API key. The page shows the key of the brand you have selected, and that brand must be on the Enterprise plan.

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

Backward compatible: you can also pass api_key as a query parameter (GET) or form field (POST). Both methods are supported.

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"
}

Important: For POST endpoints, parameters must be sent in the request body, not in the URL. Putting POST parameters in the URL query string (e.g. /new-entry?competition_id=123&user_email=...) will not work.

Rate limit

Send no more than 1 request per second. Faster calls are rejected with:

{"message": "RATE LIMIT! You are only allowed 1 API call per second."}

Rejected calls also count toward the limit, so wait a second before you retry.

Errors

Errors are returned with HTTP status 200 and a JSON body with a message field. Check for message in every response. Common messages:

Message Meaning
Invalid credentials. The API key is wrong.
API access not allowed. The brand is not on the Enterprise plan, or the giveaway is not yours.
This competition ID doesn't belong to you. The competition_id is not one of your giveaways.
RATE LIMIT! You are only allowed 1 API call per second. Slow down.
<parameter> is not set. A required parameter is missing.

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

Read Endpoints

  • GET List all users for a giveaway
  • GET List all winners for a giveaway
  • GET List all entries for a giveaway
  • GET List all giveaways
  • GET List all entries for a single user
  • GET List all giveaways a user has entered
  • GET Fetch referral link for a user

Write Endpoints

  • POST Update whitelisted emails
  • POST Add new entry method
  • POST Update an entry method
  • POST Delete an entry method
  • POST Create a giveaway
  • POST Update a giveaway
  • POST Delete a giveaway
  • POST Add a prize to a giveaway
  • POST Add an unlock reward to a giveaway
  • POST Add manual entries for a user
  • POST Enter user into a giveaway
  • POST Submit an entry with a file upload

List all users for a giveaway

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

GET https://sweepwidgetapi.com/sw_api/users

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. Page 1 returns the first 50 users. Pages 2 and later can return up to 100 rows that overlap the next page, so remove duplicates by user_id. 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",
      "custom_identifier": "your-reference-id",
      "entry_type": "User Details",
      "timestamp": "2020-06-26 11:18:21",
      "country": "United States"
    }
  ]
}

When there are no more rows, the response is a plain JSON string such as "No entries on page 50." instead of a data object.

List all winners for a giveaway

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

GET https://sweepwidgetapi.com/sw_api/winners

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",
      "custom_identifier": "your-reference-id",
      "country": "United States"
    }
  ]
}

List all entries for a giveaway

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

GET https://sweepwidgetapi.com/sw_api/entries

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",
      "custom_identifier": "your-reference-id",
      "entry_type": "Twitter Follow",
      "action": "Follow @SweepWidget On Twitter",
      "value": "@MyTwitter",
      "entry_amount": "5",
      "timestamp": "2020-06-26 11:18:21",
      "country": "United States"
    }
  ]
}

The response does not include the entry method’s entry_id. When there are no more rows, the response is a plain JSON string such as "No entries on page 50.".

List all giveaways

This method allows you to access basic information about all live, scheduled, and expired giveaways on your account (all brands).

GET https://sweepwidgetapi.com/sw_api/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. Each page looks at 50 of your giveaways (newest first, all statuses) and returns the ones that match type. A page can return fewer than 50 results, or none, even when later pages have more. Keep requesting pages until a page returns no results for every type. 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..."
    }
  ]
}

Important: The giveaway_embed_code is outputted in base 64 encoded format (because it contains HTML). You must base 64 decode this value to get the HTML. 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.

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

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

{
  "custom_identifier": null,
  "entries": [
    {
      "entry_type": "User Details",
      "action": "Login",
      "value": "Auto Verified",
      "entry_amount": 1,
      "timestamp": "2024-02-29 15:13:51"
    },
    {
      "entry_type": "Facebook Page Visit",
      "action": "NULL",
      "value": "Auto Verified",
      "entry_amount": 1,
      "timestamp": "2024-03-01 19:44:52"
    },
    {
      "entry_type": "Instagram Follow",
      "action": "NULL",
      "value": "Test",
      "entry_amount": 1,
      "timestamp": "2024-03-01 19:44:58"
    },
    {
      "entry_type": "Email Subscribe",
      "action": "NULL",
      "value": "Auto Verified",
      "entry_amount": 1,
      "timestamp": "2024-03-04 19:07:05"
    }
  ]
}

If the user has no entries, the response is a plain JSON string such as "No entries for user [email protected] in competition 123.".

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.

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

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": ["20234", "20165", "20137", "20108"]
}

If nothing is found, the response is {"message": "No results..."}.

Update whitelisted emails

This method replaces the whitelisted emails for a single competition. You can optionally replace the global whitelisted emails for all competitions of the brand.

The list you send replaces the existing list. To add one email, send the full list including it.

The list only takes effect when Only allow specific emails to enter is turned on for the giveaway (Security settings, or if_enter_whitelist = 1 in Update a giveaway).

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

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 of the brand. Accepted values: 1 or 0. Required
competition_id Integer ID of your competition. Send it on every call, including global = 1 (it must be one of your giveaways). Required
whitelisted_emails Array Specify which emails are allowed to enter. Required

Example Request

$ch = curl_init('https://sweepwidgetapi.com/sw_api/white-list-emails');
 
$post = json_encode([
  'global' => 0,
  'competition_id' => '123',
  'whitelisted_emails' => array('[email protected]', '[email protected]', '[email protected]')
]);
 
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);

Example Response

{"message": "Successfully updated whitelisted emails for competition id: 123"}

Add new entry method

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

POST https://sweepwidgetapi.com/sw_api/create-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_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). Max 255 characters. Required
entries_worth Integer How many entries the entry method is worth (1 to 9999). Required
entry_order Integer What order the entry method appears. Default: after the last entry method. Optional
mandatory Integer Whether or not it is a required entry method. 1 = required, 0 = optional (default). Optional
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. Optional
input_header String Header string after the entrant toggles open the entry method. Default: the standard text for the entry method type. Optional
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
daily String 0 = one-time (default), 1 = daily repeat. Optional
entry_level Integer 1 = pre-entry/required, 2 = bonus action (default). 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
required_actions_until_unlock Integer Unlock after this many entries. 0 = off, or 1 to 99999. Optional
tags String Entry method tags. Optional

The response includes the new method’s entry_id. Save it: you need it to update or delete the entry method, and for custom_fields / entry_id in Submit an entry with a file upload.

Available entry method types

Use these values in the entry_method_type parameter.

  • Bluesky: bluesky_comment, bluesky_follow, bluesky_like_post, bluesky_post, bluesky_repost
  • Discord: discord_join_server, discord_server_boost, discord_server_role
  • Facebook: facebook_group_visit, facebook_page_visit, facebook_post_visit, facebook_post_visits, facebook_select_media
  • Instagram: instagram_comment_post, instagram_follow, instagram_like_post, instagram_repost, instagram_select_media, instagram_submit_post, instagram_tag_friend, instagram_view_post, instagram_visit_profile
  • LinkedIn: linkedin_follow, linkedin_follow_influencer, linkedin_share
  • Pinterest: pinterest_follow_board, pinterest_follow_user, pinterest_repin_pin, pinterest_select_board, pinterest_select_pin, pinterest_submit_board, pinterest_submit_pin, pinterest_visit_board, pinterest_visit_page, pinterest_visit_pin
  • Reddit: reddit_leave_a_comment, reddit_subscribe, reddit_visit_a_page
  • Snapchat: snapchat_follow
  • Telegram: telegram_join_channel, telegram_join_group, telegram_leave_a_comment
  • Threads: threads_comment, threads_follow, threads_repost
  • TikTok: tiktok_comment, tiktok_follow, tiktok_like, tiktok_share, tiktok_visit, tiktok_watch_video
  • Tumblr: tumblr_follow, tumblr_like_post, tumblr_reblog_post
  • Twitch: twitch_follow, twitch_subscribe
  • Twitter: twitter_follow, twitter_hashtags, twitter_retweet, twitter_select_media, twitter_tweet
  • X: x_follow, x_post, x_repost
  • YouTube: youtube_channel_subscribe, youtube_comment, youtube_like_video, youtube_submit_video, youtube_visit_channel, youtube_watch
  • Kick: kick_follow, kick_subscribe
  • SoundCloud: soundcloud_follow, soundcloud_like_song, soundcloud_listen_to_song, soundcloud_repost_song, soundcloud_submit_song
  • Spotify: spotify_follow, spotify_follow_playlist, spotify_follow_podcast, spotify_listen_to_song, spotify_save
  • Vimeo: vimeo_watch_video
  • Bandcamp: bandcamp_follow
  • Crypto Wallets: bep2_crypto_wallet, btc_crypto_wallet, eth_bep20_crypto_wallet, other_crypto_wallet, solana_crypto_wallet
  • Crowdfunding: indiegogo_visit, kickstarter_visit
  • Commerce: ebay_follow, entries_for_purchase, etsy_follow, etsy_item, make_a_purchase, shopify_follow, shopify_template, woocommerce_purchases
  • Content Platforms: blog_comment, disqus_comment, goodreads_add_to_shelf, goodreads_follow, medium_clap, medium_comment, patreon_page_visit, producthunt_follow, producthunt_vote, rss, substack_subscribe
  • Events: add_to_calendar, attend_eventbrite_event, attend_eventbrite_venue
  • Actions: app_download, bonus, custom, e_signature, email_subscribe, leave_a_review, loyalty_bonus, podcast_subscribe, refer_friends, secret_code, steam_join_group, upload_a_file, visit_a_page
  • Form Fields: address, birthday, checkbox, checkboxes, complete_survey, full_name, phone_number, radio, select, text_input, textarea

Example Request

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-entry-method');
 
$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'
]);
 
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);

Example Response

{
  "message": "Successfully added entry method for competition id: 123",
  "entry_id": 5,
  "entry_method": 12,
  "entry_method_type": "facebook_page_visit"
}

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.

POST https://sweepwidgetapi.com/sw_api/update-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 update. It is returned when you create the entry method (Add new entry method). Required
entries_worth Integer How many entries the entry method is worth (1 to 9999). 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_header_value String Header text shown after the entrant opens the entry method. 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
required_actions_until_unlock Integer Unlock after this many entries. 0 = off, or 1 to 99999. Optional
tags String Entry method tags. Optional
email_integration String Email provider integration config. Optional

Example Request

$ch = curl_init('https://sweepwidgetapi.com/sw_api/update-entry-method');
 
$post = json_encode([
  'competition_id' => '123',
  'entry_method_id' => '5',
  'entries_worth' => '20',
  'entry_method_handle' => 'Follow Us On Instagram',
  'mandatory' => '1'
]);
 
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);

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.

POST https://sweepwidgetapi.com/sw_api/delete-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

$ch = curl_init('https://sweepwidgetapi.com/sw_api/delete-entry-method');
 
$post = json_encode([
  'competition_id' => '123',
  'entry_method_id' => '5'
]);
 
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);

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.

POST https://sweepwidgetapi.com/sw_api/create-giveaway

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 Brand default public or private. If omitted, the brand’s default setting for new giveaways is used.
competition_type String standard standard or photo_contest.
redirect_url String (empty) Post-entry redirect URL.
redirect_delay Integer 5 Seconds to wait before the redirect.
entry_award_mode Integer 1 1 = award entries per entry method, 2 = award entries only after all entry methods are completed.
global_entry_amount Integer 1 Entries awarded when entry_award_mode = 2.

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 4 1 = full name, 2 = full first name and last initial, 3 = first initial and full last name, 4 = aliased name (1st place user, 2nd place user, etc.).

Unlock rewards (optional)

Parameter Type Default Description
if_unlock_rewards Integer 0 Enable unlock rewards (0/1). Adding a reward with Add an unlock reward turns this on automatically.

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 0 0 = weak, 1 = standard, 2 = strong, 3 = strict.
require_captcha Integer 1 Not used: giveaways don’t show a CAPTCHA, whatever the value.
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 No extra effect (0/1). Disposable email addresses are blocked on every giveaway.
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 Legacy field. For geo-targeting, use geo_mode, geo_countries_iso, and geo_states instead (see below).
countries_allowed_include_or_exclude String include include or exclude.
geo_mode String off Geo-targeting mode: “off” (disabled), “allow” (only allow listed locations), or “block” (block listed locations). Premium plan required.
geo_countries_iso String Comma-separated ISO 3166-1 alpha-2 country codes, e.g. “US,CA,GB”. Used with geo_mode.
geo_states String JSON object for US state-level targeting. Format: {“US”:[“CA”,”NY”,”TX”]}. Only applicable when geo_countries_iso includes “US”.
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 Turn on “Only allow specific emails to enter” (0/1). Set the list with Update whitelisted emails.

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 555555 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_description_background_color String ffffff Description background color.
body_font_size Integer 16 Body font size in px.
buttons_font_color String ffffff Button text color.
buttons_background_color String 4a3aff Button background color.
buttons_font_size Integer 15 Button font size in px.
buttons_width Integer 150 Button width in px.
buttons_padding String 10 15 10 15 Button padding in px (top right bottom left).
buttons_border_radius Integer 4 Button border radius in px.
buttons_enter_text String Enter Giveaway Button text.
form_border_color String eeeeee Form border color.
form_border_width Integer 1 Form border width in px.
form_border_radius Integer 10 Form border radius in px.
form_box_shadow Integer 1 Enable form box shadow (0/1).
form_max_width Integer 600 Max form width in px.
form_font_family String Roboto Font family.
top_background_color String ffffff Countdown bar background color.
top_numbers_font_color String 4a3aff Countdown numbers color.
top_numbers_font_size Integer 24 Countdown numbers font size in px.
top_text_font_color String 777777 Countdown text color.
top_text_font_size Integer 15 Countdown text font size in px.
input_border_color String c4c4c4 Input field border color.
input_border_width Integer 1 Input field border width in px.
input_border_radius Integer 0 Input field border radius in px.
links_font_color String 4a3aff Link text color.
unlock_font_color String 555555 Unlock text color.
unlock_font_size Integer 19 Unlock text font size in px.
landing_page_background_type Integer 1 Landing page background type.
landing_page_background_color String ffffff 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).
hide_top_bottom_lines Integer 0 Hide the top and bottom lines (0/1).
remove_footer Integer 0 Remove the “Built with SweepWidget” footer (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

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-giveaway');
 
$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'
]);
 
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);

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.

POST https://sweepwidgetapi.com/sw_api/update-giveaway

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

$ch = curl_init('https://sweepwidgetapi.com/sw_api/update-giveaway');
 
$post = json_encode([
  'competition_id' => '12345',
  'title' => 'Updated Giveaway Title',
  'end_time' => '2026-04-15 23:59:59',
  'buttons_background_color' => 'FF5722'
]);
 
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);

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

POST https://sweepwidgetapi.com/sw_api/delete-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

Example Request

$ch = curl_init('https://sweepwidgetapi.com/sw_api/delete-giveaway');
 
$post = json_encode([
  'competition_id' => '12345'
]);
 
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);

Example Response

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

If the giveaway is not found or was already deleted, the response is {"message": "Giveaway not found or already deleted."}.

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.

POST https://sweepwidgetapi.com/sw_api/create-prize

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

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-prize');
 
$post = json_encode([
  'competition_id' => '12345',
  'prize_name' => '$100 Amazon Gift Card',
  'prize_winners_allowed' => '1',
  'prize_value' => '100.00',
  'prize_currency' => 'USD'
]);
 
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);

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.

POST https://sweepwidgetapi.com/sw_api/create-reward

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 (1 to 9999). 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

$ch = curl_init('https://sweepwidgetapi.com/sw_api/create-reward');
 
$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'
]);
 
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);

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.

POST https://sweepwidgetapi.com/sw_api/add-manual-entries

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
custom_identifier String Your own external reference ID for this participant (max 255 characters). Updates the identifier for this user in this giveaway. Optional

Example Request

$ch = curl_init('https://sweepwidgetapi.com/sw_api/add-manual-entries');
 
$post = json_encode([
  'competition_id' => '123',
  'entry_amount' => '1',
  'user_email' => '[email protected]'
]);
 
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);

Example Response

{
  "success": true,
  "message": "Entries successfully added.",
  "user_email": "[email protected]",
  "entries_added": "1",
  "competition_id": "123"
}

If the email has not entered the giveaway, the response is {"message": "There is no user associated with this email."}.

Enter user into a giveaway

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

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

Good to know:

  • Each email can enter a giveaway once. A second call with the same email returns {"message": "This user has already entered this competition."}. To give that user more entries, use Add manual entries for a user.
  • The API does not check the giveaway’s start time, end time or draft status. Only send entries while your giveaway is running.
  • If the email has entered one of your giveaways before, the existing participant is reused and the name you send is not applied.
  • Entries added with this endpoint do not fire webhooks.

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
custom_identifier String Your own external reference ID for this participant (max 255 characters). This value is returned in entry, user, and winner responses. Optional

Example Request

$ch = curl_init('https://sweepwidgetapi.com/sw_api/new-entry');
 
$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
  //'custom_identifier' => 'your-reference-id' // Optional: your own external reference
]);
 
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);

Example Response

{
  "message": "You have successfully entered Test User ([email protected])",
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

This method allows you to fetch a user’s referral link for one of your giveaways. The user must have entered that giveaway.

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

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

Example Response

{
  "landing_page": "https://yoursite.com/giveaway?sw-share=12345-asfdjhwe"
}

If no referral link is found, the response is {"message": "No results..."}.

Submit an entry with a file upload

This method allows you to submit an entry with a photo or video file for a giveaway that has an Upload A File entry method (this includes photo contests). The file is validated and stored the same way a widget upload is, thumbnails are generated automatically, and the participant is credited the entry amount configured on the entry method. If the participant doesn’t exist yet, they are created automatically. This is perfect for building your own entry form with a file upload field.

POST https://sweepwidget.com/sw_api/upload-entry

Note: this endpoint uses the URL above (on sweepwidget.com), and the request must be sent as multipart/form-data (not JSON) because it carries a file.

Parameters

Parameter Type Description Required
api_key String API developer key. Can also be sent as Authorization: Bearer header. Required
competition_id Integer The unique ID of the giveaway. Required
user_email String The email address of the participant. Required
file_upload File The photo or video file, sent as multipart/form-data. Allowed file types are the ones configured on the giveaway’s Upload A File entry method. Max size: 100 MB. Required
user_name String The name of the participant. Required if the participant has not entered any of your giveaways before. Optional
caption String A gallery caption shown with the submission (max 1,000 characters). Optional
entry_id Integer If the giveaway has more than one Upload A File entry method, the entry method to credit. Defaults to the first one. Optional
custom_identifier String A custom identifier stored with the participant. Optional
user_phone String The participant’s phone number, stored on their profile. Optional
custom_fields JSON object Values for the giveaway’s custom form field entry methods, as a JSON object mapping each entry method’s entry_id to the participant’s answer, e.g. {“4”: “Supermarket”, “5”: “2”}. Each saved field credits that entry method’s configured entry amount. Optional

Good to know

  • Each participant can submit one file per Upload A File entry method, unless the entry method has daily re-entry enabled.
  • If the giveaway requires media approval, the submission is created as pending and won’t show in the gallery until you approve it.
  • If the gallery has “Allow participants to submit their own entries?” set to No, the call returns “Submissions are turned off for this contest.”
  • Images are resized into gallery thumbnails automatically. Videos get a frame extracted as their thumbnail.
  • The response includes the CDN URL of the stored file and its thumbnail.
  • To pass values for custom form fields (text inputs, dropdowns, dates, etc.), add those entry methods to your giveaway, then send their values via custom_fields. Use the entry_id returned when you create the entry method with Add new entry method. The List all entries response does not include entry_id.

Example Request

curl -X POST "https://sweepwidget.com/sw_api/upload-entry" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "competition_id=123" \
  -F "[email protected]" \
  -F "user_name=Jane Smith" \
  -F "user_phone=+64211234567" \
  -F "caption=My receipt" \
  -F 'custom_fields={"4": "Supermarket", "5": "2", "6": "24/08/2026"}' \
  -F "file_upload=@/path/to/receipt.jpg"
$curl = curl_init();
 
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://sweepwidget.com/sw_api/upload-entry",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => array(
    "competition_id" => 123,
    "user_email" => "[email protected]",
    "user_name" => "Jane Smith",
    "caption" => "My sunset photo",
    "file_upload" => new CURLFile("/path/to/photo.jpg")
  ),
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer YOUR_API_KEY"
  ),
));
 
$response = json_decode(curl_exec($curl));
var_dump($response);

Example Response

{
  "success": true,
  "message": "Entry with file upload successfully added.",
  "competition_id": 123,
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_email": "[email protected]",
  "entry_id": 3,
  "entries_added": 4,
  "custom_fields_saved": [4, 5, 6],
  "file_url": "https://sweepwidgetuploads.fra1.cdn.digitaloceanspaces.com/competition/123/9f2c1b7e.jpg",
  "thumbnail_url": "https://sweepwidgetuploads.fra1.cdn.digitaloceanspaces.com/competition/123/9f2c1b7e.jpg",
  "media_status": "approved"
}