Objects

Campaign

The Campaign Object contains detailed information about a LoyaltySurf campaign.

Attributes
id	string	The unique identifier of the campaign
name	string	The campaign name
loyaltyActionCount	integer	The total loyalty action count
participantCount	integer	The total participant count
winnerCount	integer	The total number of winners††
status	string	The campaign status: DRAFT,IN_PROGRESS,COMPLETE,DELETED
rewards	array	The list of Rewards associated with the campaign

†† Winners = all participants with at least one approved reward.

Campaign Object Example

{
    "id": "abc123",
    "name": "Pied Piper Advocate Program",
    "loyaltyActionCount": 121,
    "participantCount": 199,
    "winnerCount": 1,
    "status": "IN_PROGRESS",
    "rewards": [
        {
            "id": "xyz789",
            "description": "Make a LinkedIn post mentioning Pied Piper",
            "subdescription": "Post must be less than 1 week old from date of submission",
            "instructions": "<div><p><strong>Helpful tips:</strong></p><ul><li>Talk about how you used to do things before using Pied Piper</li><li>Mention specific ROIs (e.g, time saved, revenue generated)</li></ul></div>",
            "cta": "Get $25",
            "submissionType": "URL",
            "submissionExampleUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b",
            "submissionFormUrl": "https://linkedin.com/shareArticle",
            "submissionFormFields": [
                {
                    "key": "linkedinPostUrl",
                    "label": "Your LinkedIn Post URL",
                    "placeholder": "Enter your LinkedIn Post URL here",
                    "type": "text",            
                    "isRequired": true,
                    "isVisible": true
                }
            ],
            "submissionFormButtonText": "Submit",
            "submissionFormMessages": {
                "required": "is required",
                "reCaptchaRequired": "You must pass the reCAPTCHA verification.",
                "success": "Thanks! We have received your response.",
                "error": "There was an error. Please try submitting again.",
                "alreadySubmitted": "You already submitted this form."
            },
            "isUnlimited": false,
            "limit": 1,
            "conversionsRequired": 1,
            "imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png"
            "metadata": {
              "rewardForTierA": 50,
              "rewardForTierB": 100
            }
        }
    ]
}

---

Reward

The Reward Object contains detailed reward information about a single reward for a campaign.

Note: This Reward Object is different from a ParticipantReward Object, which is a reward earned by a participant.

Attributes
id	string	The unique identifier of the reward
description	string	A description of the reward
subdescription	string	A sub-description of the reward
instructions	string	Instructions for the participant to unlock the reward (in HTML format)
cta	string	The call-to-action (CTA) for the reward
submissionType	string	The type of reward submission the participant must complete. Options: "URL", "FORM"
submissionExampleUrl	string	Only applicable if submissionType === "URL". The URL of an example of what a successful reward submission looks like
submissionFormUrl	string	Only applicable if submissionType === "FORM". The URL where the participant is expected to submit a form to redeem their reward.
submissionFormFields	array	Only applicable if submissionType === "FORM". A list of reward form field objects that the participant must submit to redeem their reward.
submissionFormButtonText	string	The text for the form submission button.
submissionFormMessages	object	Only applicable if submissionType === "FORM". An object with various validation messages for the input fields in submissionFormFields.
isUnlimited	boolean	true if this reward can be earned by a single participant an unlimited amount of times
limit	integer	The number of times a participant can earn this reward (this property is overridden with -1 if isUnlimited is true)
conversionsRequired	integer	The number of loyalty actions a participant must complete to earn this reward
imageUrl	string	The reward image URL
metadata	object	The reward metadata

Reward Object Example

{
    "id": "xyz789",
    "description": "Make a LinkedIn post mentioning Pied Piper",
    "subdescription": "Post must be less than 1 week old from date of submission",
    "instructions": "<div><p><strong>Helpful tips:</strong></p><ul><li>Talk about how you used to do things before using Pied Piper</li><li>Mention specific ROIs (e.g, time saved, revenue generated)</li></ul></div>",
    "cta": "Get $25",
    "submissionType": "URL",
    "submissionExampleUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b",
    "submissionFormUrl": "https://linkedin.com/shareArticle",
    "submissionFormFields": [
        {
            "key": "linkedinPostUrl",
            "label": "Your LinkedIn Post URL",
            "placeholder": "Enter your LinkedIn Post URL here",
            "type": "text",            
            "isRequired": true,
            "isVisible": true
        }
    ],
    "submissionFormButtonText": "Submit",
    "submissionFormMessages": {
        "required": "is required",
        "reCaptchaRequired": "You must pass the reCAPTCHA verification.",
        "success": "Thanks! We have received your response.",
        "error": "There was an error. Please try submitting again.",
        "alreadySubmitted": "You already submitted this form."
    },
    "isUnlimited": false,
    "limit": 1,
    "conversionsRequired": 1,
    "imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png"
    "metadata": {
      "rewardForTierA": 50,
      "rewardForTierB": 100
    }
}

---

Participant

The Participant Object contains detailed information about a campaign participant.

Attributes
id	integer	The unique identifier of the participant
firstName	string	The first name of the participant
lastName	string	The last name of the participant
loyaltyActionCount	integer	The total number of loyalty actions made by the participant
monthlyLoyaltyActionCount	integer	The total number of loyalty actions made this month by the participant (resets at the end of the month)
prevMonthlyLoyaltyActionCount	integer	The total number of loyalty actions made the previous month by the participant.
email	string	The email of the participant
createdAt	timestamp	The date the participant was added to the campaign (UTC milliseconds)
fraudRiskLevel	string	A value that represents the integrity of the participant: LOW, MEDIUM,HIGH
fraudReasonCode	string	A value representing the reason for the fraudRiskLevel: UNIQUE_IDENTITY, DUPLICATE_EMAIL, DUPLICATE_IDENTITY
isWinner	boolean	true if the participant has earned one or more rewards
loyaltyActionCountsPerReward	array	A breakdown of how many loyalty actions overall was performed by the participant per reward. It's an object with the campaign reward ID as the key, and the number of loyalty actions performed as the value. This key will not exist if the participant has not performed any loyalty actions, instead of being an empty object {}.
monthlyLoyaltyActionCountsPerReward	array	A breakdown of how many loyalty actions for the current month was performed by the participant per reward. It has the same shape as loyaltyActionCountsPerReward. This key will not exist if the participant has not performed any loyalty actions, instead of being an empty object {}.
loyaltyActionSource	string	The source of how the participant joined the campaign: PARTICIPANT, DIRECT,IMPORT,MANUAL
rewards	array	A list of ParticipantReward objects that the participant has earned
notes	string	A value containing internal notes about the participant, added via the LoyaltySurf Dashboard
metadata	object	An Object containing any custom key-value data, useful when you want to save additional data for the participant (e.g, company, companySize) Metadata is never used by LoyaltySurf and usage is optional. Metadata is returned in REST API calls. For more information, please see API Guidelines.
rank	integer	The rank of the participant.
monthlyRank	integer	The monthly rank of the participant. This rank resets to 0 at the end of each month.
prevMonthlyRank	integer	The previous monthly rank of the participant. This rank will not be be returned if the participant did not exist within your campaign during the previous month.

Participant Object Example

{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "loyaltyActionCount": 3,
    "monthlyLoyaltyActionCount": 3,
    "prevMonthlyLoyaltyActionCount": 0,
    "rank": 10001,
    "monthlyRank": 20001,
    "email": "[e-mail]",
    "createdAt": 1552404738928,
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTIY",
    "isWinner": true,
    "loyaltyActionCountPerReward": {
        "m5xm9l": 1,
        "w01fil": 2
    },
    "monthlyLoyaltyActionCountPerReward": {
        "m5xm9l": 1,
        "w01fil": 2
    },
    "loyaltyActionSource": "DIRECT",
    "metadata": {
       "company": "Hooli, Inc",
       "companySize": 10000
    },
    "rewards": [
        {
            "id": "9x8v1b",
            "rewardId": "m5xm9l",
            "status": "FULFILLED",
            "unread": true,
            "isAvailable": true,
            "approved": true,
            "isFulfilled": true
        },
        {
            "id": "vsdj34",
            "rewardId": "w01fil",
            "status": "FULFILLED",
            "unread": true,
            "isAvailable": true,
            "approved": true,
            "isFulfilled": true
        },
        {
            "id": "sj3kap",
            "rewardId": "w01fil",
            "status": "FULFILLED",
            "unread": true,
            "isAvailable": true,
            "approved": true,
            "isFulfilled": true
        }
    ]
}

---

ParticipantReward

The ParticipantReward Object represents a reward that the participant has earned.

Note: This ParticipantReward Object is different from a Reward Object and contains information that is only pertinent to the participant that earned the reward.

Attributes
id	string	The unique identifier of the participant's reward
rewardId	string	The ID of the Reward the participant earned
status	string	The status of the reward: PENDING,FULFILLED
isAvailable	boolean	true if the reward is available for participant to claim or redeem
approved	boolean	true if the reward has been approved
approvedAt	timestamp	The date and time the reward was approved for this participant (UTC milliseconds). It is null for unapproved rewards.
isFulfilled	boolean	true if the reward has been fulfilled.
fulfilledAt	timestamp	The date and time the reward was fulfilled for this participant (UTC milliseconds). It is null for either unapproved or unfulfilled rewards.
unread	boolean	false if the participant has not seen the reward in a LoyaltySurf window otherwise false.

ParticipantReward Object Example

{
    "id": "rr35mg",
    "rewardId": "c6w1qo",
    "status": "PENDING",
    "unread": true,
    "approved": false,
    "approvedAt": null,
    "fulfilledAt": null,
    "isAvailable": false,
    "isFulfilled": false
}

---

ParticipantRewardFormSubmission

The ParticipantRewardFormSubmission Object represents a reward form submission that the participant has filled out and sent from the advocate portal.

Note: This ParticipantRewardFormSubmission Object does not mean the participant has earned any rewards yet. You will need to approve their submission or trigger the loyalty action in order for the reward to be unlocked for them.

Attributes
id	string	The unique identifier of the reward form submission
participantId	string	The unique identifier of the Participant that submitted the form
participantEmail	string	The email address of the Participant that submitted the form
rewardId	string	The ID of the Reward the form submission is for
status	string	The status of the reward: UNREVIEWED,REVIEWED
formData	object	An Object containing the form submission details. The key-value data corresponds with the fields in Reward.submissionFormFields.

ParticipantRewardFormSubmission Object Example

{
    "id": "def678",
    "participantId": "f8g9nl",
    "participantEmail": "[e-mail]",
    "rewardId": "xyz789",
    "status": "UNREVIEWED",
    "formData": {
      "linkedinPostUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b"
    }
}