{"id":1074,"date":"2020-06-27T23:26:41","date_gmt":"2020-06-27T23:26:41","guid":{"rendered":"https:\/\/sweepwidget.com\/docs\/?p=1074"},"modified":"2026-03-06T21:37:45","modified_gmt":"2026-03-06T21:37:45","slug":"sweepwidget-api","status":"publish","type":"post","link":"https:\/\/sweepwidget.com\/docs\/sweepwidget-api","title":{"rendered":"SweepWidget API Documentation"},"content":{"rendered":"
<\/p>\n
\n
SweepWidget API Documentation<\/h1>\n
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.<\/p>\n
Base URL<\/span>https:\/\/sweepwidgetapi.com\/sw_api\/<\/span><\/div>\n<\/div>\n
<\/p>\n
Getting Your API Key<\/h2>\n
First, you must get your API Key. Navigate to Integrations<\/strong> and click on API Access<\/strong>.<\/p>\n
<\/figure>\n
<\/figure>\n
Then, copy your API Key<\/strong>.<\/p>\n
<\/figure>\n
<\/p>\n
Authentication<\/h2>\n
All API requests require authentication using your API key. Send your API key as a Bearer token<\/strong> in the Authorization<\/code> header:<\/p>\n
Backward compatible:<\/strong> You can also pass api_key<\/code> as a query parameter (GET) or form field (POST). Both methods are supported.<\/p>\n<\/div>\n
How to make requests<\/h3>\n
GET endpoints<\/strong> (reading data): Pass parameters as query string values in the URL.<\/p>\n
GET https:\/\/sweepwidgetapi.com\/sw_api\/users?competition_id=123&page_start=1\nAuthorization: Bearer YOUR_API_KEY<\/code><\/pre>\n
POST endpoints<\/strong> (writing data): Send parameters in the request body<\/strong> as JSON. Set the Content-Type<\/code> header to application\/json<\/code>.<\/p>\n
Important:<\/strong> 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=...<\/code>) will not work.<\/p>\n<\/div>\n
Quick start examples<\/h3>\n
cURL<\/p>\n
# GET - List all users for a giveaway\ncurl \"https:\/\/sweepwidgetapi.com\/sw_api\/users?competition_id=123&page_start=1\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n\n# POST - Enter a user into a giveaway\ncurl -X POST \"https:\/\/sweepwidgetapi.com\/sw_api\/new-entry\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\n \"competition_id\": 123,\n \"user_name\": \"Jane\",\n \"user_email\": \"jane@example.com\",\n \"entry_amount\": 1,\n \"giveaway_link\": \"https:\/\/yoursite.com\"\n }'<\/code><\/pre>\n
Python<\/p>\n
import requests\n\nAPI_KEY = \"YOUR_API_KEY\"\nheaders = {\"Authorization\": f\"Bearer {API_KEY}\"}\n\n# GET - List all users for a giveaway\nresponse = requests.get(\n \"https:\/\/sweepwidgetapi.com\/sw_api\/users\",\n params={\"competition_id\": 123, \"page_start\": 1},\n headers=headers\n)\nprint(response.json())\n\n# POST - Enter a user into a giveaway\nresponse = requests.post(\n \"https:\/\/sweepwidgetapi.com\/sw_api\/new-entry\",\n json={\n \"competition_id\": 123,\n \"user_name\": \"Jane\",\n \"user_email\": \"jane@example.com\",\n \"entry_amount\": 1,\n \"giveaway_link\": \"https:\/\/yoursite.com\"\n },\n headers=headers\n)\nprint(response.json())<\/code><\/pre>\n
JavaScript (Node.js)<\/p>\n
const API_KEY = \"YOUR_API_KEY\";\nconst headers = {\n \"Authorization\": `Bearer ${API_KEY}`,\n \"Content-Type\": \"application\/json\"\n};\n\n\/\/ GET - List all users for a giveaway\nconst usersRes = await fetch(\n \"https:\/\/sweepwidgetapi.com\/sw_api\/users?competition_id=123&page_start=1\",\n { headers }\n);\nconst users = await usersRes.json();\n\n\/\/ POST - Enter a user into a giveaway\nconst entryRes = await fetch(\n \"https:\/\/sweepwidgetapi.com\/sw_api\/new-entry\",\n {\n method: \"POST\",\n headers,\n body: JSON.stringify({\n competition_id: 123,\n user_name: \"Jane\",\n user_email: \"jane@example.com\",\n entry_amount: 1,\n giveaway_link: \"https:\/\/yoursite.com\"\n })\n }\n);\nconst result = await entryRes.json();<\/code><\/pre>\n
{\n \"data\": [\n {\n \"competition_id\": 123,\n \"competition_url\": \"ahej14f9\",\n \"type\": \"Live\",\n \"title\": \"My Giveaway Title\",\n \"description\": \"This is the description of my awesome giveaway!\",\n \"rules\": \"US, CA, 18+\",\n \"start_time\": \"2020-07-28 00:00:00\",\n \"end_time\": \"2020-08-28 00:00:00\",\n \"time_zone\": \"America\/Chicago\",\n \"number_of_winners\": \"5\",\n \"image_loc\": \"https:\/\/sweepwidget.com\/images\/my-image.jpg\",\n \"giveaway_embed_code\": \"PGRpdiBpZD0i...\"\n }\n ]\n}<\/code><\/pre>\n
Important:<\/strong> 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);<\/em><\/div>\n
\n \n<\/p>\n
List all entries for a single user in a giveaway<\/h2>\n
This method allows you to list all of the entries a user has completed in a single giveaway.<\/p>\n
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.<\/p>\n
![\"\"](\"https:\/\/sweepwidget.com\/docs\/wp-content\/uploads\/2020\/06\/api-docs-1-1024x568.png\")
<\/figure>\n![\"\"](\"https:\/\/sweepwidget.com\/docs\/wp-content\/uploads\/2020\/06\/api-docs-2-1024x567.png\")
<\/figure>\n![\"\"](\"https:\/\/sweepwidget.com\/docs\/wp-content\/uploads\/2020\/06\/api-docs-3-1024x567.png\")
<\/figure>\n