Integrate Uplup's powerful contest platform into your applications with our comprehensive API.
Welcome to the Uplup contests API! Use our RESTful API to programmatically create and manage contests, users, entries, and winners. The API is available on the Ultimate Plan.
All requests require your API key as a header or parameter.
Fetch a list of all contests. No parameters are required for this endpoint. Just include your API key.
curl -X GET https://api.uplup.com/api_endpoint/fetch-all-contests -H 'Authorization: YOUR_API_KEY'
{ "success": true, "response": [ { "contests_id": "a1h27f89", "title": "$100 Amazon Gift Card Giveaway", "More fields..." } ] }
Fetch info about a specific contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
curl -X GET "https://api.uplup.com/api_endpoint/fetch-contest?contests_id=YOUR_CONTESTS_ID" -H 'Authorization: YOUR_API_KEY'
{ "success": true, "response": { "contests_id": "a1h27f89", "title": "$100 Amazon Gift Card Giveaway", "More fields..." } }
Create a new contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
title | Plain text | Title of the contest | Yes |
start_date | YYYY-MM-DD HH:MM:SS | Start date and time of the contest (default value is today at midnight) | Optional |
end_date | YYYY-MM-DD HH:MM:SS | End date and time of the contest (default value is 30 days from not at 23:59:00) | Optional |
description | html | Description of the contest (use HTML tags) | Optional |
if_terms_and_conditions | true or false | Flag for terms and conditions (default value is false) | Optional |
curl -X POST https://api.uplup.com/api_endpoint/create-contest -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "title": "Contest Title", "description": "Contest Description" }'
{ "success": true, "response": "Your contest has been created successfully.", "contests_id": "12345", "link": "https://uplup.com/f/12345" }
Update an existing contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
title | Plain text | Title of the contest | Yes |
start_date | YYYY-MM-DD HH:MM:SS | Start date and time of the contest (default value is today at midnight) | Optional |
end_date | YYYY-MM-DD HH:MM:SS | End date and time of the contest (default value is 30 days from not at 23:59:00) | Optional |
description | html | Description of the contest (use HTML tags) | Optional |
curl -X POST https://api.uplup.com/api_endpoint/update-contest -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "contests_id": "YOUR_CONTESTS_ID", "title": "Contest Title", "description": "Contest Description" }'
{ "success": true, "response": "Your contest has been successfully updated.", "contests_id": "YOUR_CONTESTS_ID" }
Delete an existing contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
curl -X POST https://api.uplup.com/api_endpoint/delete-contest -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "contests_id": "YOUR_CONTESTS_ID" }'
{ "success": "true", "message": "Contest 12345 has been successfully deleted.", "contests_id": "12345" }
Fetch all users in an existing contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
curl -X GET "https://api.uplup.com/api_endpoint/fetch-all-contest-users?contests_id=YOUR_CONTESTS_ID" -H 'Authorization: YOUR_API_KEY'
{ "success": true, "response": [ { "user_id": "eloyvr98b137lo995g03qt8vw8gx88vimixhiaay", "entries_sum": 3, "is_winner": 0, "is_winner_timestamp": null, "name": "Graham", "email": "[email protected]", "photo_url": false, "referral_hash": "edqsd9fa" } ] }
Fetch all entries in an existing contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
curl -X GET "https://api.uplup.com/api_endpoint/fetch-all-contest-entries?contests_id=YOUR_CONTESTS_ID" -H 'Authorization: YOUR_API_KEY'
{ "success": true, "response": [ { "contests_entries_id": "fat6uaq6080lc2y4asf6onasauxoecmhyqj5of7g", "contests_id": "jdm97b0c", "user_id": "eloyvr98b137lo995g03qt8vw8gx88vimixhiaay", "email": "[email protected]", "entry_methods_id": "field-ea3b8996-2910-4f9b-8449-946b133c6522", "entry_level": 1, "entry_methods_allow_edits": 0, "field_name": "Email", "input_label": "Email", "require_validation": 0, "entry_value": "[email protected]", "entry_amount": 1, "status": 1, "api_verified": 0, "is_winner": 0, "timestamp": 1692624364 } ] }
Fetch all entries for a user in an existing contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
user_email | Plain text | Email of the user | Yes |
curl -X GET "https://api.uplup.com/api_endpoint/[email protected]" -H 'Authorization: YOUR_API_KEY'
{ "success": true, "response": [ { "entries_id": "12345", "contest_id": "abcdef", "contest_title": "Win a Prize", "entry_method": "email", "entry_count": 1, "timestamp": "2024-01-01 12:00:00" } ] }
Add a new user to an existing contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
user_name | Plain text | Full name of the user | Yes |
user_email | Plain text | Email address of the user | Yes |
entry_amount | Number | Number of entries for this user | Yes |
photo_url | Plain text | URL to the photo of the user | Optional |
birthday_day | DD | Birth day of user in 2 number format | Optional |
birthday_month | MM | Birth day of user in 2 number format | Optional |
birthday_year | YYYY | Birth day of user in 4 number format | Optional |
country_code | 2 letter country code | Country code of the user | Optional |
region | Plain text | Region of the user | Optional |
referred_by | Plain text | Email address of the participant who referred this user (you must have a Refer A Friend entry method on this contest for this to work) | Optional |
curl -X POST https://api.uplup.com/api_endpoint/add-user -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "contests_id": "YOUR_CONTESTS_ID", "user_name": "John Doe", "user_email": "[email protected]", "entry_amount": "1", "photo_url": "", "birthday_day": "06", "birthday_month": "15", "birthday_year": "1991", "country_code": "US", "region": "North Carolina", "referred_by": "" }'
{ "success": true, "response": "John Doe has been successfully added to the contest.", "contests_id": "YOUR_CONTESTS_ID", "user_name": "John Doe", "user_email": "[email protected]", "user_id": "12345" }
Delete all entries for an existing user in an existing contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
user_email | Plain text | Email address of the user | Yes |
curl -X POST https://api.uplup.com/api_endpoint/delete-user -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "contests_id": "YOUR_CONTESTS_ID", "user_email": "[email protected]" }'
{ "success": "true", "message": "Contest 12345 has been successfully deleted.", "contests_id": "12345" }
Delete a single entry for an existing user from an existing contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
curl -X POST https://api.uplup.com/api_endpoint/delete-single-entry -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "contests_id": "YOUR_CONTESTS_ID", "contests_entries_id": "123456789" }'
{ "success": "true", "message": "Contest 12345 has been successfully deleted.", "contests_id": "12345" }
Fetch all winners for an existing contest.
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
curl -X GET "https://api.uplup.com/api_endpoint/fetch-all-winners?contests_id=YOUR_CONTESTS_ID" -H 'Authorization: YOUR_API_KEY'
{ "success": true, "response": [ { "user_id": "eloyvr98b137lo995g03qt8vw8gx88vimixhiaay", "entries_sum": 3, "is_winner": 1, "is_winner_timestamp": 1692624364, "name": "Graham", "email": "[email protected]", "photo_url": false, "referral_hash": "edqsd9fa" } ] }
Add new entry method to an existing contest
Name | Accepted Values | Description | Required |
---|---|---|---|
contests_id | Plain text | ID of your contest | Yes |
field_name | Plain text | The name of the field, e.g., 'Instagram Follow Profile'. Here is a list of all the field names | Yes |
field_header | Plain text | The header of the field, displayed to users | Yes |
question | Boolean | Indicates if the field is a question | No |
instructions | Plain text | Instructions for the field, if any | No |
options | JSON/Array | Additional options for the field | No |
required_value | Plain text | The required answer if validation is needed | No |
entry_url | URL | URL for the entry method | No |
entry_amount | Number | The amount of entries this method will generate | No |
button_text | Plain text | Text on the submission button | No |
if_daily | Boolean | Determines if the entry method can be performed daily | No |
daily | Number | Number of daily entries allowed | No |
required | Boolean | Indicates if the field is required | No |
require_validation | Boolean | Indicates if the field requires validation | No |
validation_question | Plain text | Question prompted for validation | No |
form_field | Boolean | Indicates if this is a form field | No |
api_verification | Boolean | Determines if API verification is needed | No |
icon | CSS class | FontAwesome CSS class for the icon e.g. 'fa-instagram' | Yes |
icon_color | Color (hex) | Hex color code for the icon | Yes |
icon_background_color | Color (hex) | Hex background color code for the icon | Yes |
curl -X POST https://api.uplup.com/api_endpoint/add-new-entry-method -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "contests_id": "YOUR_CONTESTS_ID", "entry_method": "social_share", "entry_value": "1" }'
{ "success": true, "response": "The entry method has been updated successfully.", "contests_id": "YOUR_CONTESTS_ID" }
curl -X GET https://api.uplup.com/api_endpoint/fetch-all-contests -H 'Authorization: YOUR_API_KEY'
{ "success": true, "response": [ { "contests_id": "a1h27f89", "title": "$100 Amazon Gift Card Giveaway", "More fields..." } ] }