API Documentation

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

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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes

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

NameAccepted ValuesDescriptionRequired
titlePlain textTitle of the contestYes
start_dateYYYY-MM-DD HH:MM:SSStart date and time of the contest (default value is today at midnight)Optional
end_dateYYYY-MM-DD HH:MM:SSEnd date and time of the contest (default value is 30 days from not at 23:59:00)Optional
descriptionhtmlDescription of the contest (use HTML tags)Optional
if_terms_and_conditionstrue or falseFlag 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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes
titlePlain textTitle of the contestYes
start_dateYYYY-MM-DD HH:MM:SSStart date and time of the contest (default value is today at midnight)Optional
end_dateYYYY-MM-DD HH:MM:SSEnd date and time of the contest (default value is 30 days from not at 23:59:00)Optional
descriptionhtmlDescription 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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes

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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes

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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes

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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes
user_emailPlain textEmail of the userYes

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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes
user_namePlain textFull name of the userYes
user_emailPlain textEmail address of the userYes
entry_amountNumberNumber of entries for this userYes
photo_urlPlain textURL to the photo of the userOptional
birthday_dayDDBirth day of user in 2 number formatOptional
birthday_monthMMBirth day of user in 2 number formatOptional
birthday_yearYYYYBirth day of user in 4 number formatOptional
country_code2 letter country codeCountry code of the userOptional
regionPlain textRegion of the userOptional
referred_byPlain textEmail 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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes
user_emailPlain textEmail address of the userYes

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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes

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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes

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

NameAccepted ValuesDescriptionRequired
contests_idPlain textID of your contestYes
field_namePlain textThe name of the field, e.g., 'Instagram Follow Profile'. Here is a list of all the field namesYes
field_headerPlain textThe header of the field, displayed to usersYes
questionBooleanIndicates if the field is a questionNo
instructionsPlain textInstructions for the field, if anyNo
optionsJSON/ArrayAdditional options for the fieldNo
required_valuePlain textThe required answer if validation is neededNo
entry_urlURLURL for the entry methodNo
entry_amountNumberThe amount of entries this method will generateNo
button_textPlain textText on the submission buttonNo
if_dailyBooleanDetermines if the entry method can be performed dailyNo
dailyNumberNumber of daily entries allowedNo
requiredBooleanIndicates if the field is requiredNo
require_validationBooleanIndicates if the field requires validationNo
validation_questionPlain textQuestion prompted for validationNo
form_fieldBooleanIndicates if this is a form fieldNo
api_verificationBooleanDetermines if API verification is neededNo
iconCSS classFontAwesome CSS class for the icon e.g. 'fa-instagram'Yes
icon_colorColor (hex)Hex color code for the iconYes
icon_background_colorColor (hex)Hex background color code for the iconYes

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