NAV

Introduction

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

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",
        "start_ts": "123456789",
        "end_ts": "123456789",
      },
      {
        "id": 2,
        "title": "Promotion 2 Title",
        "start_ts": "123456789",
        "end_ts": "123456789",
      }
  }
]

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

Return Values

Parameter Description
id unique identifier of the promotion
title title of the promotion
start_ts UTC timestamp of the promotion start date
end_ts UTC timestamp of the promotion end date

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",
        "ip": "Cheshire, CT",
        "end_ts": "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 UTC 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

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 manty 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

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