The "Refer a Friend" template comes with it's own form as part of the In-app Referral Widget™. However, if you would rather have participants join in a different way, you can do that too with a little bit of coding.

This is useful in several cases:

  • You have a web app and you want your users to see the In-app Referral Widget only after they have logged-in.

  • Your landing page is built on Unbounce, Instapage or other similar CMS and you want participants to join the referral campaign only after submitting one of the forms on your website.

  • You want people to verify their email address before joining as participants in your referral campaign.

In such cases, you need to manually submit the participant to Viral Loops. 

Client-side submission

Firstly, make sure you have added the Viral Loops javascript embeddable widget snippet before the closing <body> tag in your page. You can get this snippet at the Installation step of your campaign wizard. 

After the form is submitted, run the following:

    firstname: "the user's first name",
    lastname: "the user's last name",
    email: "the user's e-mail",
    "extraData": { "internal-ID": "1234", "favourite-colour": "blue" }
}, function() {
    //optional callback
  • The firstname, lastname and email values are taken from your form.

  • firstname and lastname are optional.

  • The extra data are other data you want to capture about the participant. These are only visible on a special campaign export that we provide on demand.

This submits the participant to the campaign.

Server-side submission

In case you want to submit the participant the campaign via an API call, here's what you need to use:

Method: POST
Headers: "Content-Type: application/json"

Example request body:

    "params": {
        "event": "registration",
        "user": {
            "firstname": "",
            "lastname": "",
            "email": "",
            "extraData": { "internal-ID": "1234"}
        "referrer": {
            "referralCode": "",
            "email": ""
        "refSource": ""
    "apiToken": "s3cretApiT0cken"
  • referrer (optional): You can use either the referralEmail or referralCode for the referrer. In case of the referralCode, the value should have been captured from the request's querystring that brought the user to the page.

  • refSource (optional): the referral channel that the user followed to land into the page.
    The value should have been captured from the request's querystring that brought the user to the page.
    Valid values are: facebook/twitter/reddit/email/copy

  • apiToken (required): The API token of your campaign which you can find in the installation step of your campaign's wizard

Example response:

  "referralCode": "E13i-LMv",
  "eventId": "evt_M2VhNTRiMGExMDMwMGYxZmFkMGY",
  "isNew": true

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






            "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.




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


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



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

However, after that part, you will still need to do the client-side campaign.identify as before, so that the widget will load the user's unique referral URL and sharing options.

Note: This article does not apply to Squarespace pages, due to restrictions/limitations.

Did this answer your question?