The Viral Loops Developer Hub

Welcome to the Viral Loops developer hub. You'll find comprehensive guides and documentation to help you start working with Viral Loops as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

How can I make custom calls to your API?

Viral Loops provides an API to allow access to the features currently included in the widget.

You may use it to integrate and adapt our system to your application specific needs.

Verification keys

All API calls will need one (or both) of the following:

1. The unique campaign hash
2. The apiToken

You can find these both in the Installation step of your campaign wizard:

Note: This is you private key and should be kept secret(not used in clients)

Getting campaign info

This can be used to display campaign data, like copywrites, sharing links, participation fields, enabled social channels, tweet/reddit lists, expiration counter and more.

GET https://app.viral-loops.com/api/Campaigns/find_by_hash?ucid=CAMPAIGN_HASH&apiToken=MYAPITOKEN

Example response:

{
  "type": "ranking",
  "genericConfig": {
    "x": "5",
    "inputFields": {
      "firstName": {
        "enabled": true,
        "text": "Your first name"
      },
      "lastName": {
        "enabled": false,
        "text": "Your last name"
      },
      "email": {
        "enabled": true,
        "text": "Your email address"
      }
    },
    "termsConditions": {
      "enabled": false,
      "termsConditionsText": "By joining our referral program, you agree to our Terms & Conditions",
      "termsConditionsUrl": ""
    },
(.....)
  "sharingOptions": {
    "facebook": {
      "enabled": true,
      "details": []
    },
    "twitter": {
      "enabled": true,
      "details": [
        {
          "tweet": [
            ""
          ]
        },
        {
          "via": ""
        }
      ]
    },

 (.....)
}

Participation

This registers a new participant.

POST https://app.viral-loops.com/api/v1/participation

Post parameters

  • participationDataJson: A json object containing the following fields : firstname, lastname (if enabled for this campaign) and email
  • extraDataJson (Optional): A json object with custom data you may need to send to enable advance sorting/filtering from our admin panel.
  • refCode (Optional): the referral code of the referrer (if there was one)
  • refSource (Optional): the channel the referrer used. Valid options are: facebook, twitter, reddit, email, copy
  • countryCode (Optional): the country code of the participant in ISO 3166-1 Alpha 2 format(GR,FR etc)
  • ucid: The unique campaign hash
  • apiToken: Your apiToken

Example response

The referral code of the new participant will be returned:

{
  "refCode": "NyPTD8cQ-"
}

Inviting through social channels

Tracks shares per channel and sends email invites.

POST https://app.viral-loops.com/api/v1/social_action

Post parameters

  • referralCode: the referral code of the participant doing the invite
  • postType: the channel name, valid values are : facebook, twitter, reddit, email, copy
  • postData: only used in the case of the email type, an array of valid emails must be provided here
  • apiToken: Your apiToken

Example response

{
  "status": "ok"
}

Getting participant stats

If you want to display the number of referrals for a participant (or number of entries in the case of a Temping Giveaway campaign) then you can use the following API call:

GET https://app.viral-loops.com/api/v1/rank_and_leaderboard?apiToken=MYAPITOKEN&referralCode=CODE_OF_CURRENT_PARTICIPANT

This returns a response with the data for the selected participant. For example:

{
  "firstname": "Dimitris",
  "entries": 1,
  "rank": 79,
  "leaderboard": [
    {
      "leadname": "Dimitris"
    }
  ]
}

If you ommit the referral code then you get a JSON containing the participants at the top of your leaderboard (or waitlist).

How can I make custom calls to your API?