API Reference

This reference documents the LoyaltySurf REST API, including all available public methods and examples of each.

Open in Postman

Easily test these API methods dynamically by using our Postman Collection. Just change the Token in the Authorizations tab, and the campaign_id variable to the campaign you're working on.

Campaigns

Get Campaign

GET https://api.loyaltysurf.io/v1/campaign/:id

Retrieves a campaign for the given ID.

Path Parameters

200 Returns the campaign object

{
    "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/loyaltysurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png"
        }
    ]
}

Get Campaigns

GET https://api.loyaltysurf.io/v1/campaigns

Retrieves a list of your campaigns. Campaigns that have been deleted will not be returned in this response.

200 Returns the campaign objects.

{
    "campaigns": [
        {
            "id": "abc123",
            "name": "Pied Piper Advocate Program",
            "loyaltyActionCount": 20500,
            "participantCount": 40000,
            "winnerCount": 1500,
            "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/loyaltysurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png"
                }
            ]
        },
        {
            "id": "ljtqn5",
            "name": "Pied Piper Advocate Program #2",
            "loyaltyActionCount": 30500,
            "participantCount": 60000,
            "winnerCount": 750,
            "status": "IN_PROGRESS",
            "rewards": [
                {
                    "id": "qiar1r",
                    "description": "Make an X (Twitter) post about 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 $15",
                    "submissionType": "URL",
                    "submissionExampleUrl": "https://x.com/Sarah_S/status/2307836134014308344",
                    "submissionFormUrl": "https://x.com/compose/post",
                    "submissionFormFields": [
                        {
                            key: "twitterPostUrl",
                            label: "Your Twitter Post URL",
                            placeholder: "Enter your Twitter Post URL here",
                            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/loyaltysurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png"
                }
            ]
        }
    ]
}

Loyalty Actions

Trigger Loyalty Action by Email

POST https://api.loyaltysurf.io/v1 /campaign/:id/loyalty-action

Triggers a loyalty action for a person, awarding loyalty action credit to them and adds them to the campaign as a participant if they do not already exist.

If the required number of loyalty actions of the campaign reward is reached, then the reward will be unlocked.

Path Parameters

Request Body

200 Returns an object with a success attribute equal to true if loyalty action was triggered otherwise false. Also contains the updated participant that performed the loyalty action, or the newly-created participant if `addParticipantIfNoneExists` was specified.

{
    "success": true,
    "message": "Successfully awarded loyalty action credit.",
    "participant": {
        "campaignId": "6396fbff31a4f20865f4ae93",
        "id": "cq3e6a",
        "createdAt": "2022-12-14T08:58:10.019Z",
        "email": "[e-mail]",
        "fraudReasonCode": "UNIQUE_IDENTITY",
        "fraudRiskLevel": "LOW",
        "hasRewards": true,
        "isWinner": false,
        "loyaltyActionCount": 1,
        "loyaltyActionSource": "DIRECT",
        "monthlyLoyaltyActionCount": 1,
            "prevMonthlyLoyaltyActionCount": 0,
            "sanitizedEmail": "[e-mail]",
            "unapprovedRewardsCount": 1,
            "unfulfilledRewardsCount": 1,
            "unsubscribed": false,
            "updatedAt": "2022-12-14T08:58:10.407Z",
            "welcomeEmailSent": true,
            "loyaltyActionCountPerReward": {
                "xfj7ic": 1
            },
            "monthlyLoyaltyActionCountPerReward": {
                "xfj7ic": 1
            }
        }
    }
}

Metadata: Please see our API Guidelines for more information about metadata.

Trigger Loyalty Action by Participant ID

POST https://api.loyaltysurf.io/v1/campaign/:id/loyalty-action

Triggers a loyalty action for an existing participant.

If the required number of loyalty actions of the campaign reward is reached, then the reward will be unlocked.

Path Parameters

Request Body

200 Returns an object with a success attribute equal to true if loyalty action was triggered otherwise false. Also contains the updated participant that performed the loyalty action.

{
    "success": true,
    "message": "Successfully awarded loyalty action credit.",
    "participant": {
        "campaignId": "6396fbff31a4f20865f4ae93",
        "id": "cq3e6a",
        "createdAt": "2022-12-14T08:58:10.019Z",
        "email": "[e-mail]",
        "fraudReasonCode": "UNIQUE_IDENTITY",
        "fraudRiskLevel": "LOW",
        "hasRewards": true,
        "isWinner": false,
        "loyaltyActionCount": 1,
        "loyaltyActionSource": "DIRECT",
        "monthlyLoyaltyActionCount": 1,
            "prevMonthlyLoyaltyActionCount": 0,
            "sanitizedEmail": "[e-mail]",
            "unapprovedRewardsCount": 1,
            "unfulfilledRewardsCount": 1,
            "unsubscribed": false,
            "updatedAt": "2022-12-14T08:58:10.407Z",
            "welcomeEmailSent": true,
            "loyaltyActionCountPerReward": {
                "xfj7ic": 1
            },
            "monthlyLoyaltyActionCountPerReward": {
                "xfj7ic": 1
            }
        }
    }
}

Participants

Get Participant by ID

GET https://api.loyaltysurf.io/v1/campaign/:id/participant/:participantId

Retrieves a single participant from a campaign using the given participant ID.

Path Parameters

200 Returns the participant object.

{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "loyaltyActionCount": 2,
    "monthlyloyaltyActionCount": 2,
    "prevMonthlyLoyaltyActionCount": 0,
    "rank": 10001,
    "monthlyRank": 20001,
    "monthlyRank": -1,
    "email": "[e-mail]",
    "createdAt": 1552404738928,
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTIY",
    "isWinner": true,
    "loyaltyActionCountPerReward": {
        "xfj7ic": 1
    },
    "monthlyLoyaltyActionCountPerReward": {
        "xfj7ic": 1
    },
    "loyaltyActionSource": "DIRECT",
    "metadata": {
       "company": "Hooli, Inc",
       "companySize": 10000
    },
    "unsubscribed": false,
    "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
        }
    ]
}

Get Participant by Email

GET https://api.loyaltysurf.com/v1/campaign/:id/participant/:participantEmail

Retrieves a single participant from a campaign using the given participant email.

Path Parameters

200 Returns the participant object.

{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "loyaltyActionCount": 2,
    "monthlyloyaltyActionCount": 2,
    "prevMonthlyLoyaltyActionCount": 0,
    "rank": 10001,
    "monthlyRank": 20001,
    "monthlyRank": -1,
    "email": "[e-mail]",
    "createdAt": 1552404738928,
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTIY",
    "isWinner": true,
    "loyaltyActionCountPerReward": {
        "xfj7ic": 1
    },
    "monthlyLoyaltyActionCountPerReward": {
        "xfj7ic": 1
    },
    "loyaltyActionSource": "DIRECT",
    "metadata": {
       "company": "Hooli, Inc",
       "companySize": 10000
    },
    "unsubscribed": false,
    "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
        }
    ]
}

Get Participants

GET https://api.loyaltysurf.io/v1/campaign/:id/participants

Retrieves a list of participants in the campaign.

Path Parameters

Query Parameters

200 Returns the participant objects.

{
    "participants": [
        {
            "id": "f8g9nl",
            "firstName": "Gavin",
            "lastName": "Belson",
            "loyaltyActionCount": 2,
            "monthlyloyaltyActionCount": 2,
            "prevMonthlyLoyaltyActionCount": 0,
            "rank": 10001,
            "monthlyRank": 20001,
            "monthlyRank": -1,
            "email": "[e-mail]",
            "createdAt": 1552404738928,
            "fraudRiskLevel": "LOW",
            "fraudReasonCode": "UNIQUE_IDENTIY",
            "isWinner": true,
            "loyaltyActionCountPerReward": {
                "xfj7ic": 1
            },
            "monthlyLoyaltyActionCountPerReward": {
                "xfj7ic": 1
            },
            "loyaltyActionSource": "DIRECT",
            "metadata": {
               "company": "Hooli, Inc",
               "companySize": 10000
            },
            "unsubscribed": false,
            "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
                }
            ]
        },
        {
            "id": "wskljf9",
            "firstName": "Spongebob",
            "lastName": "Squarepants",
            "loyaltyActionCount": 0,
            "monthlyLoyaltyActionCount": 0,
            "prevMonthlyLoyaltyActionCount": 0,
            "rank": 1540,
            "monthlyRank": 1540,
            "prevMonthlyRank": 1799,
            "email": "[e-mail]",
            "createdAt": 1552404738928,
            "fraudRiskLevel": "LOW",
            "fraudReasonCode": "UNIQUE_IDENTIY",
            "isWinner": true,            
            "loyaltyActionSource": "MANUAL",
            "metadata": {},
            "unsubscribed": false,
            "rewards": []
        }
    ],
    "limit": 2,
    "nextId": "1u7v0q"
}

Get Leaderboard

GET https://api.loyaltysurf.io/v1/campaign/:id/leaderboard

Retrieves a list of participants in the campaign ordered by loyalty action count in ascending order. Monthly Loyalty Action Count Leaderboard You can retrieve the campaign leaderboard ordered by the monthly loyalty action count by providing a query parameter leaderboardType with a value of CURRENT_MONTH. This will retrieve a list of participants ordered by monthly loyalty action. Monthly loyalty action counts are automatically reset at the end of each month for each participant within your campaign, therefore results of the monthly loyalty action count may vary. Previous Monthly Loyalty Action Count Leaderboard Similar to the monthly campaign leaderboard, providing a query parameter of leaderboardType with a value of PREV_MONTH will retrieve a list of participants ordered by the previous monthly loyalty action count. Participants that did not exist within the campaign during the previous month will not be returned within the previous monthly leaderboard response.

Path Parameters

Query Parameters

200 Example response of the standard leaderboard with returned participants ordered by their loyalty action count. If the leaderboardType=CURRENT_MONTH query parameter is provided, the resulting list would be ordered by monthly loyalty action count. Similarly, if leaderboardType=PREV_MONTH is provided, the resulting list would be ordered by the previous monthly loyalty action count.

{
    "participants": [
        {
            "id": "f8g9nl",
            "firstName": "Gavin",
            "lastName": "Belson",
            "loyaltyActionCount": 2,
            "monthlyloyaltyActionCount": 2,
            "prevMonthlyLoyaltyActionCount": 0,
            "rank": 10001,
            "monthlyRank": 20001,
            "monthlyRank": -1,
            "email": "[e-mail]",
            "createdAt": 1552404738928,
            "fraudRiskLevel": "LOW",
            "fraudReasonCode": "UNIQUE_IDENTIY",
            "isWinner": true,
            "loyaltyActionCountPerReward": {
                "xfj7ic": 1
            },
            "monthlyLoyaltyActionCountPerReward": {
                "xfj7ic": 1
            },
            "loyaltyActionSource": "DIRECT",
            "metadata": {
               "company": "Hooli, Inc",
               "companySize": 10000
            },
            "unsubscribed": false,
            "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
                }
            ]
        },
        {
            "id": "wskljf9",
            "firstName": "Spongebob",
            "lastName": "Squarepants",
            "loyaltyActionCount": 0,
            "monthlyLoyaltyActionCount": 0,
            "prevMonthlyLoyaltyActionCount": 0,
            "rank": 10002,
            "monthlyRank": 1540,
            "prevMonthlyRank": 1799,
            "email": "[e-mail]",
            "createdAt": 1552404738928,
            "fraudRiskLevel": "LOW",
            "fraudReasonCode": "UNIQUE_IDENTIY",
            "isWinner": true,            
            "loyaltyActionSource": "MANUAL",
            "metadata": {},
            "unsubscribed": false,
            "rewards": []
        }
    ],
    "limit": 2,
    "nextId": "1u7v0q"
}

Add Participant

POST https://api.loyaltysurf.io/v1/campaign/:id/participant

Adds a participant to the campaign.

Path Parameters

Request Body

200 Example response of participant that was added to the campaign. Returns the participant object.

{
    "id": "3vxff9",
    "firstName": "Gavin",
    "lastName": "Belson",
    "loyaltyActionCount": 0,
    "monthlyLoyaltyActionCount": 0,
    "prevMonthlyLoyaltyActionCount": 0,
    "rank": 10001,
    "monthlyRank": 10001,
    "rewards": [],
    "email": "[e-mail]",
    "createdAt": 1558665537426,
    "loyaltyActionSource": "DIRECT",
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTITY",
    "isWinner": false,
    "metadata": {
       "company": "Hooli, Inc",
       "companySize": 10000
    }
    "unsubscribed": false,
}

Metadata: Please see our API Guidelines for more information about metadata.

Update Participant by ID

POST https://api.loyaltysurf.io/v1/campaign/:id/participant/:participantId

Updates a participant within the campaign using the ID of the participant.

Path Parameters

Request Body

200 Returns the updated participant object

{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "loyaltyActionCount": 2,
    "monthlyloyaltyActionCount": 2,
    "prevMonthlyLoyaltyActionCount": 0,
    "rank": 10001,
    "monthlyRank": 20001,
    "monthlyRank": -1,
    "email": "[e-mail]",
    "createdAt": 1552404738928,
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTIY",
    "isWinner": true,
    "loyaltyActionCountPerReward": {
        "xfj7ic": 1
    },
    "monthlyLoyaltyActionCountPerReward": {
        "xfj7ic": 1
    },
    "loyaltyActionSource": "DIRECT",
    "metadata": {
       "company": "Hooli, Inc",
       "companySize": 10000
    },
    "unsubscribed": false,
    "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
        }
    ]
}

*Please see our API Guidelines for more information about metadata.

Update Participant by Email

POST https://api.loyaltysurf.io/v1/campaign/:id/participant/:participantEmail

Updates a participant within the campaign using the email of the participant.

Path Parameters

Request Body

200 Returns the updated participant object

{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "loyaltyActionCount": 2,
    "monthlyloyaltyActionCount": 2,
    "prevMonthlyLoyaltyActionCount": 0,
    "rank": 10001,
    "monthlyRank": 20001,
    "monthlyRank": -1,
    "email": "[e-mail]",
    "createdAt": 1552404738928,
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTIY",
    "isWinner": true,
    "loyaltyActionCountPerReward": {
        "xfj7ic": 1
    },
    "monthlyLoyaltyActionCountPerReward": {
        "xfj7ic": 1
    },
    "loyaltyActionSource": "DIRECT",
    "metadata": {
       "company": "Hooli, Inc",
       "companySize": 10000
    },   
    "unsubscribed": false,
    "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
        }
    ]
}

*Please see our API Guidelines for more information about metadata.

Remove Participant by ID

DELETE https://api.loyaltysurf.io/v1/campaign/:id/participant/:participantId

Removes a participant within the campaign using the ID of the participant.

Path Parameters

200 Returns a success response.

{
    "success": true
}

Remove Participant by Email

DELETE https://api.loyaltysurf.io/v1/campaign/:id/participant/:participantEmail

Removes a participant within the campaign using the email of the participant.

Path Parameters

200 Returns a success response.

{
    "success": true
}

Participant Rewards

Get Participant Rewards by Participant ID

GET https://api.loyaltysurf.io/v1/campaign/:id/participant/:participantId/rewards

Retrieves a list of rewards earned by a participant.

Path Parameters

Query Parameters

200 In this example we are showing two rewards earned by the participant. The status value will be PENDING if the reward has not yet been fulfilled otherwise, it will be FULFILLED. isAvailable The isAvailable value will be true if the reward has been approved either manually or automatically, depending on the campaign settings and fulfilled. Otherwise it will be set to false.

{
    "limit": 2,
    "nextId": "v2qtfq",
    "rewards": [
        {
            "id": "rr35mg",
            "rewardId": "c6w1qo",
            "status": "PENDING",
            "unread": true,
            "approved": false,
            "approvedAt": null,
            "fulfilledAt": null,            
            "isAvailable": false,
            "isFulfilled": false
        },
        {
            "id": "oltj0s",
            "rewardId": "c6w1qo",
            "status": "FULFILLED",
            "unread": false,
            "approved": true,  
            "approvedAt": 1659453091744,
            "fulfilledAt": 1659453418901,     
            "isAvailable": true,
            "isFulfilled": true
        }
    ]
}

400 Error response returned if the limit query parameter that is provided exceeds the maximum allowed amount.

{
    "name": "BadRequestError",
    "code": "BAD_REQUEST_ERROR",
    "message": "Invalid request. Request params are missing or are invalid",
    "status": 400,
    "supportUrl": "https://loyaltysurf.io/settings#contact_support",
    "errors": [
        {
            "location": "query",
            "param": "limit",
            "value": "20",
            "msg": "Limit cannot be more than 10."
        }
    ],
    "level": "error",
    "timestamp": "2019-12-31T22:07:49.957Z"
}

Get Participant Rewards by Participant Email

GET https://api.loyaltysurf.io/v1/campaign/:id/participant/:participantEmail/rewards

Retrieves a list of rewards earned by a participant. Paging this response Each response will contain a nextId, that value is the id of the next participant and not the email therefore, you must use this endpoint in conjunction of our Get Participant Rewards by ID endpoint if you wish to page results starting with this endpoint. To page you would provide the nextId as the participantId path parameter within the Get Participant Rewards by ID request.

Path Parameters

Query Parameters

200 See Get Participant Rewards by ID endpoint for a more detailed description of the response.

{
    "limit": 2,
    "nextId": "v2qtfq",
    "rewards": [
        {
            "id": "rr35mg",
            "rewardId": "c6w1qo",
            "status": "PENDING",
            "unread": true,
            "approved": false,      
            "approvedAt": null,
            "fulfilledAt": null,  
            "isAvailable": false,
            "isFulfilled": false
        },
        {
            "id": "oltj0s",
            "rewardId": "c6w1qo",
            "status": "FULFILLED",
            "unread": false,
            "approved": true,    
            "approvedAt": 1659453091744,
	    "fulfilledAt": 1659453418901,
            "isAvailable": true,
            "isFulfilled": true
        }
    ]
}

Approve Participant Reward

POST https://api.loyaltysurf.io/v2/campaign/:id/reward/:rewardId/approve

Approve a reward that was earned by a participant. You should only use this endpoint if your reward automation level is set to Manually approve rewards (learn more here). This means ParticipantRewards will be generated with status: "PENDING", approved: false, and isFulfilled: false.

Calling this endpoint to approve a reward will cause New Participant Reward emails to be sent out and automations/integrations to be triggered. If you are using Webhooks to automate rewards, a new PARTICIPANT_REACHED_A_GOAL event will be emitted with data.reward.approved as false.

Path Parameters

Request Body

200 Returns a success response.

{
    "success": true
}

406 Error response returned if a reward has already been approved for a participant.

{
    "name": "InvalidRewardState",
    "code": "INVALID_REWARD_STATE",
    "message": "Invalid reward state. Reward has already been approved.",
    "status": 406,
    "supportUrl": "https://loyaltysurf.io/settings#contact_support",
    "level": "error",
    "timestamp": "2019-10-13T16:43:05.902Z"
}

Fulfill Participant Reward

POST https://api.loyatysurf.io/v1/campaign/:id/reward/:rewardId/fulfill

Fulfill a reward that was earned by a participant (this can only be done if the reward is already approved). When you call this endpoint, the ParticipantReward should have the following key-values: status: "PENDING", approved: true, and isFulfilled: false.

Fulfilling a reward does not trigger any emails or automations. It helps you stay organized when managing rewards from your LoyaltySurf admin dashboard.

Path Parameters

200 Returns a success response.

{
    "success": true
}

406 Error response returned if a reward has not been approved or has already been fulfilled.

{
    "name": "InvalidRewardState",
    "code": "INVALID_REWARD_STATE",
    "message": "Invalid reward state. Reward has already been fulfilled.",
    "status": 406,
    "supportUrl": "https://loyaltysurf.io/settings#contact_support",
    "level": "error",
    "timestamp": "2019-10-13T16:43:05.902Z"
}

Remove Participant Reward

DELETE https://api.loyaltysurf.io/v1/campaign/:id/reward/:rewardId

Remove a reward that was earned by a participant. This only applies if your campaign was configured with manual reward approval and if the provided participant reward has not been approved.

Path Parameters

200 Returns a success response.

{
    "success": true
}

406 Error response returned if a reward has already been approved.

{
    "name": "InvalidRewardState",
    "code": "INVALID_REWARD_STATE",
    "message": "Invalid reward state. This reward has already been approved and cannot be removed.",
    "status": 406,
    "supportUrl": "https://loyaltysurf.io/settings#contact_support",
    "level": "error",
    "timestamp": "2019-10-17T16:43:05.902Z"
}