NAV

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 here: Viralsweep Pricing.

We've provided some 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 of the Viralsweep API endpoints will return a JSON response.

More examples and a PHP SDK will be provided as soon as they are available. We recommend using Postman for testing API endpoints.

Authentication

All requests require the x-api-key header such as:


<?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);
?>

Make sure to replace YOUR-API-KEY-HERE with your API key.

Viralsweep requires an API key to access our API endpoints. You can register a new API key in your account settings page here: Account Settings.

The Viralsweep API endpoints expect an API key to be included in all requests. Please provide the API key in a header that looks like the following:

x-api-key: 77fea188aa192ccd0aa02693cbbfef4797c27039a31b61e8_123u

Brands

Get All Brands

Example requests to brands API endpoint:


<?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));
?>

The brands endpoint returns JSON:

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

This endpoint retrieves all brands.

HTTP Request

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

Return Values

This endpoint will return an array of all brands in your Viralsweep account. Each array contains the following values:

Parameter Description
id unique identifier of the brand
name name of the brand

Promotions

Get All Promotions

Example requests to brands API endpoint:


<?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));
?>

The promotions endpoint returns JSON:

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

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 if you want to fetch archived promotions
active set to true if you want to fetch only active promotions

Return Values

Parameter Description
id unique identifier of the promotion
title title of the promotion
type type of promotion
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 setup to run in.

Entries

Get All Entries

Example requests to entries API endpoint:


<?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));
?>

The entries endpoint returns JSON:

[
  "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",
          },
        ],        
      },           
  }
]

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 action 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 use to gain referrals
login_link URL you can send users to auto login
rank Returned when searching for a specific email address on waitlist promotions
entries_used Returned on on instant win promotions
referred_by Email address of referring entrant

Add Entry

Example requests to entry API endpoint:


<?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));
?>

The entries endpoint returns JSON:

[
  "success":   1,
  "url":   "https://swee.ps/fdgdS",
]

Example of an entry error JSON:

[
  "error":   1,
  "message": "bad_email",
]

This endpoint adds a new entry.

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
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 address of the user who referred this entrant. must be an existing email entered already into the promotion.

Custom Fields

For custom fields, you will need to add the fields to your entry form first, then visit your entry form, and using the browser inspect tool, select the field and find its ID. If you need assistance with this, please contact us.

Return Values

Parameter Description
success only returned if entry was accepted
error only returned if there was a error
message explanation of the result
url short url for new entrant

Add Entry Points

Example requests to entry points API endpoint:


<?PHP
$post_fields = array('email'=>'jdoe@gmail.com','points'=>'5','description'=>'For visting 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));
?>

The entries endpoint returns JSON:

[
  "success":   1,
  "message": "Points Updated",
]

This endpoint adds points to 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
points how many points to add (or subtract if value is negative)
description explanation of the points added or subtracted

Return Values

Parameter Description
success only returned if entry was accepted
error only returned if there was a error
message explanation of the result

Entry Validation

Example requests to entry points API endpoint:


<?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));
?>

The entries endpoint returns JSON:

[
  "success":   1,
  "message": "Validation Updated",
]

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 addresses of the entrants to change validation data. Accepts comma separated list for bulk updating.
validation values allowed are "valid", "invalid", "accept", or "unaccept".

Return Values

Parameter Description
success only returned if entry was accepted
error only returned if there was a error
message explanation of the result

Winners

Get All Winners

Example requests to winners API endpoint:


<?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));
?>

The winners endpoint returns JSON:

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

  }
]

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 brand
begin_ts UNIX timestamp to filter winners by date won
end_ts UNIX timestamp to filter winners by date won

Return Values

Parameter Description
email email of the winner
ip ip of winner
entered_ts UNIX timestamp of the winner's entry date
created_ts UNIX timestamp of the winner's win date
prize title of prize if available
code winning entry code if available

Errors

Example of an error JSON:

[
  "error":  "Could not authenticate"
]

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

Return Values

Parameter Description
error explaination of the error