ViralKit Contests API Documentation

Introduction

Welcome to the ViralKit contests API! You can view code examples in the area to the right, and you can switch the programming language of the examples with the tabs in the top right. You can also switch the API endpoint you're viewing using the tabs in the top left. Note: The API is available on the Ultimate Plan.

Fetch all contests

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

Endpoint: https://api.viralkit.com/api_endpoint/fetch-all-contests

Method: GET

No parameters required

Fetch contest info

Fetch info about a specific contest.

Endpoint: https://api.viralkit.com/api_endpoint/fetch-contest

Method: GET

Parameters

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

Create new contest

Create a new contest.

Endpoint: https://api.viralkit.com/api_endpoint/create-contest

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

Update existing contest

Update an existing contest.

Endpoint: https://api.viralkit.com/api_endpoint/update-contest

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

Delete existing contest

Delete an existing contest.

Endpoint: https://api.viralkit.com/api_endpoint/delete-contest

Method: POST

Parameters

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

Fetch all contest users

Fetch all users in an existing contest.

Endpoint: https://api.viralkit.com/api_endpoint/fetch-all-contest-users

Method: GET

Parameters

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

Fetch all contest entries

Fetch all entries in an existing contest.

Endpoint: https://api.viralkit.com/api_endpoint/fetch-all-contest-entries

Method: GET

Parameters

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

Fetch all entries for a user

Fetch all entries for a user in an existing contest.

Endpoint: https://api.viralkit.com/api_endpoint/fetch-user-entries

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

Add new user

Add a new user to an existing contest.

Endpoint: https://api.viralkit.com/api_endpoint/add-user

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

Delete user

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

Endpoint: https://api.viralkit.com/api_endpoint/delete-user

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

Delete single entry

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

Endpoint: https://api.viralkit.com/api_endpoint/delete-single-entry

Method: POST

Parameters

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

Fetch all contest winners

Fetch all winners for an existing contest.

Endpoint: https://api.viralkit.com/api_endpoint/fetch-all-winners

Method: GET

Parameters

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

Add new entry method

Add new entry method to an existing contest

Endpoint: https://api.viralkit.com/api_endpoint/add-new-entry-method

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

Fetch All Contests API Request

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

Expected JSON Output

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