Get the participant rank

Returns data about the participants in the waiting list or leaderboard. Only participants that have not been flagged are returned (see below). Use this to programmatically check who is at the top of the waiting list or leaderboard.

Be careful if you are using this API call to create your own waiting list (or leaderboard) widget. Do not use this API call publicly as it will expose the personal data of your participants. Instead, make sure to clean up the returned data in your backend first to remove personal information (eg. emails).

GET https://app.viral-loops.com/api/v2/participant_rank 

A header Content-Type: application/json  is needed.

Request parameters

{
  "apiToken": "MY_TOKEN",
  "params": {
      "participants": [{
        "email": "efi@viral-loops.com"
      }, {
        "referralCode": "JFI876FDD"
      }]
  },
  "filter": {
  "limit": 50,
  "skip": 0
  }
}
  • apiToken: The campaign's secret apiToken. Available in the installation step of the campaign wizard.
  • participants (optional): a list of participant emails or referralCodes to get information from. In this example we request the rank of the participant with email “efi@viral-loops.com” and the participant with referralCode “JFI876FDD”. If omitted or the list is empty, information for all the participants will be returned ordered by their rank. (with a limit of 50, see filter below)
  • filter (optional): Use the filter with a limit and skip argument to paginate through the results. The default (and max) limit is 50 and skip is 0 by default. Say you have 120 participants. You will need to run the call 3 times to get information for all of them. The first time with limit:50, skip:0 the first 50 participants will be returned. Then with limit:50 and skip:50 to get the next batch and then with limit:50 and skip:100 for the remaining 20. 

Successful response

{
    "data": [
        {
            "user": {
                "email": "efi@viral-loops.com",
                "firstname": "efi",
                "lastname": "",
                "referralCode": "H6Ht5nZWG",
                "createdAt": "2017-12-03 17:12:29",
                "uniqueLink": "https://mycampaign.com?referralCode=H6Ht5nZWG",
                "extraData": { "internalID": "1234" },
                "rank": 11,
                "excluded": false
            },
            "referrer": {},
            "counters": {
                "referrals": {
                    "total": 5,
                    "facebook": 1,
                    "twitter": 0,
                    "reddit": 0,
                    "copy": 3,
                    "email": 1
                },
                "shares": {
                    "total": 11,
                    "facebook": 4,
                    "twitter": 4,
                    "reddit": 0,
                    "email": 3
                }
            }
        },
        {
            "user": {
                "email": "alex@viral-loops.com",
                "firstname": "alex",
                "lastname": "",
                "referralCode": "JFI876FDD",
                "createdAt": "2017-12-03 18:29:08",
                "uniqueLink": "https://mycampaign.com?referralCode=JFI876FDD",
                "extraData": { "internalID": "1234" },
                "rank": 12,
                "excluded": false
            },
            "referrer": {
                "email": "theo@viral-loops.com",
                "firstname": "theo",
                "lastname": "",
                "referralCode": "H6Ht5nZWG",
                "createdAt": "2017-12-03 17:12:29",
                "uniqueLink": "https://mycampaign.com?referralCode=H6Ht5nZWG",
                "extraData": { "internalID": "9876" }
                "rank": 3
            },
            "counters": {
                "referrals": {
                    "total": 4,
                    "facebook": 2,
                    "twitter": 1,
                    "reddit": 0,
                    "copy": 1,
                    "email": 0
                },
                "shares": {
                    "total": 10,
                    "facebook": 4,
                    "twitter": 4,
                    "reddit": 1,
                    "email": 1
                }
            }
        }
    ]
}

For flagged participants, "excluded" is true in the user object in the response.

Flag participants

For the Startup Pre-launch and Leaderboard Giveaway campaigns, this API call is used to flag participants that have gotten early access or a reward and should be removed from the waiting list or leaderboard. The participants are not deleted from the campaign, they are simply excluded from the waitlist or leaderboard. This means they are also not displayed in the waitlist or leaderboard in the Viral Loops popup but you can still see them in your Campaign Dashboard and campaign exports.

POST https://app.viral-loops.com/api/v2/flag_participants  

A header Content-Type: application/json  is needed.

Request Parameters

{
  "apiToken": "MY_TOKEN",
  "params": {
      "participants": [{
        "email": "dimitris@viral-loops.com"
      }, {
        "email": "dimlucas@viral-loops.com"
      }, {
        "referralCode": "JFI876FDE"
      }]
  }
}
  • apiToken: The campaign's secret apiToken. Available in the installation step of the campaign wizard.
  • participants: a list of participant emails or referralCodes of the participants to be flagged.

Successful response

{
    "status": "ok"
}

GDPR consent

If you want to capture GDPR consent as well, use the following:

{

    "apiToken":"MY_TOKEN",

    "params":{

        "event":"registration",

        "user":{

            "firstname": "the user's firstname",

            "lastname": "the user's lastname",

            "email":"the user's email",

            "extraData": { "internalID": "1234" },

            "consents": {

              "2": true // 2 is the ID of the consent.

            }

        },

        "referrer":{

            "referralCode": "the referrer's referralCode (if available)"

        },

        "refSource": "the refSource (if available)"

    }

}

Consent ID

GDPR consents can be added and enabled in the Settings page of the app. The consent ID is displayed here:

Rate limit

For all API calls, there is a rate limit of 70 requests per minute.

Did this answer your question?