API Documentation

Integrate Uplup's powerful contest platform into your applications with our comprehensive API.

API Endpoints

Getting Started

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.

Base URL

Authentication

All requests require your API key as a header or parameter.

Fetch all contests

Fetch a list of all contests. No parameters are required for this endpoint. Just include your API key.

Endpoint

Method

GET

No parameters required

Code Example

curl -X GET https://api.uplup.com/api_endpoint/fetch-all-contests
-H 'Authorization: YOUR_API_KEY'

Expected JSON Output

{
  "success": true,
  "response": [
    {
      "contests_id": "a1h27f89",
      "title": "$100 Amazon Gift Card Giveaway",
      "More fields..."
    }
  ]
}

Fetch contest info

Fetch info about a specific contest.

Endpoint

Method

GET

Parameters

Name	Accepted Values	Description	Required
contests_id	Plain text	ID of your contest	Yes

Code Example

curl -X GET "https://api.uplup.com/api_endpoint/fetch-contest?contests_id=YOUR_CONTESTS_ID"
-H 'Authorization: YOUR_API_KEY'

Expected JSON Output

{
  "success": true,
  "response": {
    "contests_id": "a1h27f89",
    "title": "$100 Amazon Gift Card Giveaway",
    "More fields..."
  }
}

Create new contest

Create a new contest.

Endpoint

Method

POST

Parameters

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

Code Example

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

Expected JSON Output

{
  "success": true,
  "response": "Your contest has been created successfully.",
  "contests_id": "12345",
  "link": "https://uplup.com/f/12345"
}

Update existing contest

Update an existing contest.

Endpoint

Method

POST

Parameters

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

Code Example

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

Expected JSON Output

{
  "success": true,
  "response": "Your contest has been successfully updated.",
  "contests_id": "YOUR_CONTESTS_ID"
}

Delete existing contest

Delete an existing contest.

Endpoint

Method

POST

Parameters

Name	Accepted Values	Description	Required
contests_id	Plain text	ID of your contest	Yes

Code Example

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

Expected JSON Output

{
  "success": "true",
  "message": "Contest 12345 has been successfully deleted.",
  "contests_id": "12345"
}

Fetch all contest users

Fetch all users in an existing contest.

Endpoint

Method

GET

Parameters

Name	Accepted Values	Description	Required
contests_id	Plain text	ID of your contest	Yes

Code Example

curl -X GET "https://api.uplup.com/api_endpoint/fetch-all-contest-users?contests_id=YOUR_CONTESTS_ID"
  -H 'Authorization: YOUR_API_KEY'

Expected JSON Output

{
  "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 contest entries

Fetch all entries in an existing contest.

Endpoint

Method

GET

Parameters

Name	Accepted Values	Description	Required
contests_id	Plain text	ID of your contest	Yes

Code Example

curl -X GET "https://api.uplup.com/api_endpoint/fetch-all-contest-entries?contests_id=YOUR_CONTESTS_ID"
  -H 'Authorization: YOUR_API_KEY'

Expected JSON Output

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

Fetch all entries for a user in an existing contest.

Endpoint

Method

GET

Parameters

Name	Accepted Values	Description	Required
contests_id	Plain text	ID of your contest	Yes
user_email	Plain text	Email of the user	Yes

Code Example

curl -X GET "https://api.uplup.com/api_endpoint/[email protected]"
  -H 'Authorization: YOUR_API_KEY'

Expected JSON Output

{
  "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 new user

Add a new user to an existing contest.

Endpoint

Method

POST

Parameters

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

Code Example

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

Expected JSON Output

{
  "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 user

Delete all entries for an existing user in an existing contest.

Endpoint

Method

POST

Parameters

Name	Accepted Values	Description	Required
contests_id	Plain text	ID of your contest	Yes
user_email	Plain text	Email address of the user	Yes

Code Example

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

Expected JSON Output

{
  "success": "true",
  "message": "Contest 12345 has been successfully deleted.",
  "contests_id": "12345"
}

Delete single entry

Delete a single entry for an existing user from an existing contest.

Endpoint

Method

POST

Parameters

Name	Accepted Values	Description	Required
contests_id	Plain text	ID of your contest	Yes

Code Example

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

Expected JSON Output

{
  "success": "true",
  "message": "Contest 12345 has been successfully deleted.",
  "contests_id": "12345"
}

Fetch all contest winners

Fetch all winners for an existing contest.

Endpoint

Method

GET

Parameters

Name	Accepted Values	Description	Required
contests_id	Plain text	ID of your contest	Yes

Code Example

curl -X GET "https://api.uplup.com/api_endpoint/fetch-all-winners?contests_id=YOUR_CONTESTS_ID"
  -H 'Authorization: YOUR_API_KEY'

Expected JSON Output

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

Add new entry method to an existing contest

Endpoint

Method

GET

Parameters

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

Code Example

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

Expected JSON Output

{
  "success": true,
  "response": "The entry method has been updated successfully.",
  "contests_id": "YOUR_CONTESTS_ID"
}

Code Example

curl -X GET https://api.uplup.com/api_endpoint/fetch-all-contests
-H 'Authorization: YOUR_API_KEY'

Expected JSON Output

{
  "success": true,
  "response": [
    {
      "contests_id": "a1h27f89",
      "title": "$100 Amazon Gift Card Giveaway",
      "More fields..."
    }
  ]
}