Introduction to ViralSweep's API

Welcome to the ViralSweep API. You can use our API to access endpoints to add and retrieve data within your ViralSweep account.

To access the API, you need the ViralSweep Premium Plan or higher. View pricing →

We've provided usage examples written in PHP and cURL. These examples should be enough to demonstrate how to make calls to the same endpoints from different programming languages. All API endpoints return a JSON response.

We recommend using Postman for testing API endpoints.

Authentication

ViralSweep requires an API key to access all endpoints. Register a new API key in your Account Settings.

Include your API key in every request as a request header:

x-api-key: YOUR-API-KEY-HERE

ℹ Replace YOUR-API-KEY-HERE with your personal API key from Account Settings.

PHP / cURL

<?php
$process = curl_init();
curl_setopt($process, CURLOPT_URL,
  'https://app.viralsweep.com/api/brands');
curl_setopt($process, CURLOPT_HTTPHEADER, array(
  'content-type: application/json',
  'x-api-key: YOUR-API-KEY-HERE'
));
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($process);
curl_close($process);
?>

Brands

GET Get All Brands

This endpoint retrieves all brands in your ViralSweep account.

HTTP Request

GET https://app.viralsweep.com/api/brands

Return Values

Returns an array of all brands. Each item contains:

Parameter	Description
id	Unique identifier of the brand
name	Name of the brand

✓ Don't forget to include the x-api-key header in your request!

PHP / cURL

<?php
$process = curl_init();
curl_setopt($process, CURLOPT_URL,
  'https://app.viralsweep.com/api/brands');
curl_setopt($process, CURLOPT_HTTPHEADER, array(
  'content-type: application/json',
  'x-api-key: YOUR-API-KEY-HERE'
));
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($process);
curl_close($process);
print_r(json_decode($return));
?>

Response

{
  "brands": [
    {
      "id": 1,
      "name": "Company1"
    },
    {
      "id": 2,
      "name": "Company2"
    }
  ]
}

Promotions

GET Get All Promotions

This endpoint retrieves all promotions for a brand.

HTTP Request

GET https://app.viralsweep.com/api/promotions/<BRAND_ID>

URL Parameters

Parameter	Description
<BRAND_ID>	Unique identifier of the brand
all	Set to `true` to fetch archived promotions
active	Set to `true` to fetch only active promotions

Return Values

Parameter	Description
id	Unique identifier of the promotion
title	Title of the promotion
type	Type of promotion (e.g. sweeps, photo)
start_ts	UNIX timestamp of the promotion start date
end_ts	UNIX timestamp of the promotion end date
timezone	The time zone the promotion is set to run in

✓ Don't forget to include the x-api-key header in your request!

PHP / cURL

<?php
$process = curl_init();
curl_setopt($process, CURLOPT_URL,
  'https://app.viralsweep.com/api/promotions/<BRAND_ID>');
curl_setopt($process, CURLOPT_HTTPHEADER, array(
  'content-type: application/json',
  'x-api-key: YOUR-API-KEY-HERE'
));
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($process);
curl_close($process);
print_r(json_decode($return));
?>

Response

{
  "promotions": [
    {
      "id": 1,
      "title": "Promotion 1 Title",
      "type": "sweeps",
      "start_ts": "123456789",
      "end_ts": "123456789",
      "timezone": "(GMT-05:00) Eastern Time"
    }
  ]
}

Entries

GET Get All Entries

This endpoint retrieves all entries for a promotion.

HTTP Request

GET https://app.viralsweep.com/api/entries/<PROMOTION_ID>

URL Parameters

Parameter	Description
<PROMOTION_ID>	Unique identifier of the promotion
page	Numeric value of which page to query
count	Number of results per page (defaults to 25)
query	Wildcard search term to query email addresses

Return Values

Parameter	Description
bonus	Array of data about bonus actions completed
email	Email address of the entrant
entered_ts	UNIX timestamp of when the user entered
entries_total	Total entries a user has earned
fields	Array of data user submitted via entry form
ip	IP address
location	Geo-location based on IP address lookup
referrals_count	Total referrals a user has earned
short_url	URL user can share to gain referrals
login_link	URL you can send users to auto login
rank	Returned when searching a specific email on waitlist promotions
entries_used	Returned on instant win promotions
referred_by	Email address of referring entrant

✓ Don't forget to include the x-api-key header in your request!

PHP / cURL

<?php
$process = curl_init();
curl_setopt($process, CURLOPT_URL,
  'https://app.viralsweep.com/api/entries/<PROMOTION_ID>');
curl_setopt($process, CURLOPT_HTTPHEADER, array(
  'content-type: application/json',
  'x-api-key: YOUR-API-KEY-HERE'
));
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($process);
curl_close($process);
print_r(json_decode($return));
?>

Response

{
  "entries": [
    {
      "email": "testuser@viralsweep.com",
      "entered_ts": "1561016558",
      "location": "Cheshire, CT",
      "ip": "64.12.33.27",
      "entries_total": "24",
      "referrals_count": "2",
      "short_url": "https://swee.ps/XyTRls",
      "fields": {
        "first_name": "John",
        "last_name": "Smith"
      },
      "bonus": [{
        "title": "Entering",
        "entries": "5",
        "time": "123456789"
      }]
    }
  ]
}

POST Add Entry

This endpoint adds a new entry to a promotion.

HTTP Request

POST https://app.viralsweep.com/api/entries/<PROMOTION_ID>

Parameters

Parameter	Description
<PROMOTION_ID>	Unique identifier of the promotion
email *	Email address of the entrant (required)
first_name	Entrant's first name
last_name	Entrant's last name
phone	Entrant's phone number
address	Entrant's address
address2	Entrant's address line 2
city	Entrant's city
state	Entrant's state
zip	Entrant's postal code
country	Entrant's country
birthday_month	Entrant's birth month
birthday_day	Entrant's birth day
birthday_year	Entrant's birth year
referrer_email	Email of the referring entrant (must already exist in the promotion)

Custom Fields

For custom fields, add them to your entry form first, then use the browser inspector to find the field's id attribute and use that as the parameter key.

✓ Don't forget to include the x-api-key header in your request!

Return Values

Parameter	Description
success	Only returned if entry was accepted
url	Referral share URL for the new entrant
error	Only returned if there was an error
message	Explanation of the result

PHP / cURL

<?php
$post_fields = array(
  'email'      => 'jdoe@gmail.com',
  'first_name' => 'John',
  'last_name'  => 'Doe'
);

$process = curl_init();
curl_setopt($process, CURLOPT_URL,
  'https://app.viralsweep.com/api/entries/<PROMOTION_ID>');
curl_setopt($process, CURLOPT_HTTPHEADER, array(
  'content-type: application/json',
  'x-api-key: YOUR-API-KEY-HERE'
));
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($process, CURLOPT_POSTFIELDS,
  json_encode($post_fields));
curl_setopt($process, CURLOPT_CUSTOMREQUEST, 'POST');
$return = curl_exec($process);
curl_close($process);
print_r(json_decode($return));
?>

Success Response

{
  "success": 1,
  "url": "https://swee.ps/fdgdS"
}

Error Response

{
  "error": 1,
  "message": "bad_email"
}

POST Add Entry Points

This endpoint adds (or subtracts) points for an entrant.

HTTP Request

POST https://app.viralsweep.com/api/points/<PROMOTION_ID>

Parameters

Parameter	Description
<PROMOTION_ID>	Unique identifier of the promotion
email *	Email address of the entrant (required)
points	Points to add (use a negative value to subtract)
description	Explanation of the points added or subtracted

✓ Don't forget to include the x-api-key header in your request!

Return Values

Parameter	Description
success	Only returned if points were updated
error	Only returned if there was an error
message	Explanation of the result

PHP / cURL

<?php
$post_fields = array(
  'email'       => 'jdoe@gmail.com',
  'points'      => '5',
  'description' => 'For visiting our page'
);

$process = curl_init();
curl_setopt($process, CURLOPT_URL,
  'https://app.viralsweep.com/api/points/<PROMOTION_ID>');
curl_setopt($process, CURLOPT_HTTPHEADER, array(
  'content-type: application/json',
  'x-api-key: YOUR-API-KEY-HERE'
));
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($process, CURLOPT_POSTFIELDS,
  json_encode($post_fields));
curl_setopt($process, CURLOPT_CUSTOMREQUEST, 'POST');
$return = curl_exec($process);
curl_close($process);
print_r(json_decode($return));
?>

Response

{
  "success": 1,
  "message": "Points Updated"
}

POST Entry Validation

This endpoint validates or invalidates entries by email address.

HTTP Request

POST https://app.viralsweep.com/api/validate/<PROMOTION_ID>

Parameters

Parameter	Description
<PROMOTION_ID>	Unique identifier of the promotion
email *	Email address(es) of the entrants. Accepts a comma-separated list for bulk updates.
validation	Allowed values: `valid`, `invalid`, `accept`, `unaccept`

✓ Don't forget to include the x-api-key header in your request!

Return Values

Parameter	Description
success	Only returned if validation was updated
error	Only returned if there was an error
message	Explanation of the result

PHP / cURL

<?php
$post_fields = array(
  'email'      => 'jdoe@gmail.com',
  'validation' => 'valid'
);

$process = curl_init();
curl_setopt($process, CURLOPT_URL,
  'https://app.viralsweep.com/api/validate/<PROMOTION_ID>');
curl_setopt($process, CURLOPT_HTTPHEADER, array(
  'content-type: application/json',
  'x-api-key: YOUR-API-KEY-HERE'
));
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($process, CURLOPT_POSTFIELDS,
  json_encode($post_fields));
curl_setopt($process, CURLOPT_CUSTOMREQUEST, 'POST');
$return = curl_exec($process);
curl_close($process);
print_r(json_decode($return));
?>

Response

{
  "success": 1,
  "message": "Validation Updated"
}

Winners

GET Get All Winners

This endpoint retrieves all winners for a promotion.

HTTP Request

GET https://app.viralsweep.com/api/winners/<PROMOTION_ID>

URL Parameters

Parameter	Description
<PROMOTION_ID>	Unique identifier of the promotion
begin_ts	UNIX timestamp to filter winners from this date
end_ts	UNIX timestamp to filter winners up to this date

✓ Don't forget to include the x-api-key header in your request!

Return Values

Parameter	Description
email	Email of the winner
ip	IP address of the winner
entered_ts	UNIX timestamp of the winner's entry date
created_ts	UNIX timestamp of when they won
prize	Title of prize, if available
code	Winning entry code, if available

PHP / cURL

<?php
$process = curl_init();
curl_setopt($process, CURLOPT_URL,
  'https://app.viralsweep.com/api/winners/<PROMOTION_ID>');
curl_setopt($process, CURLOPT_HTTPHEADER, array(
  'content-type: application/json',
  'x-api-key: YOUR-API-KEY-HERE'
));
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($process);
curl_close($process);
print_r(json_decode($return));
?>

Response

{
  "winners": [
    {
      "email": "winner@domain.com",
      "ip": "123.123.123.123",
      "entered_ts": "123456789",
      "created_ts": "123456789",
      "prize": "Prize Title Here"
    }
  ]
}

Errors

ℹ Our API is in beta. We will expand on this section as our API endpoints require it.

The ViralSweep API will return a JSON response if there is an error authenticating.

Return Values

Parameter	Description
error	Explanation of the error

Error Response

{
  "error": "Could not authenticate"
}