ViralKit API Documentation
Introduction
Welcome to the ViralKit API! You can use our API to access the ViralKit API endpoints, which can get information on various contests, users, and entries. 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
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 value 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..."
}
]
}