# Events Reference

## `PARTICIPANT_SUBMITTED_REWARD_FORM`

**Description:** When a participant submits a reward form from the advocate portal

```json
{
  "event": "PARTICIPANT_SUBMITTED_REWARD_FORM",
  "createdAt": 1558345202613,
  "data": {
    "id": "prfs_def678",
    "participantId": "x9a7uu",
    "participantEmail": "richard@piedpiper.com",
    "rewardId": "crew_xlj123",
    "status": "UNREVIEWED",
    "formData": {
      "linkedinPostUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b"
    },  
    "participant": {
      "id": "x9a7uu",
      "email": "richard@piedpiper.com",
      "firstName": "Richard",
      "lastName": "Hendricks",
      "notes": "",
      "rank": 9,
      "isWinner": true,
      "loyaltyActionCount": 11,
      "monthlyLoyaltyActionCount": 8,
      "prevMonthlyLoyaltyActionCount": 0,
      "createdAt": 1554431962667,
      "loyaltyActionSource": "DIRECT",
      "fraudRiskLevel": "LOW",
      "fraudReasonCode": "UNIQUE_IDENTITY",
      "metadata": {
        "piedPiperUserId": "12a39-8aajd-1dwiq",
        "companyName": "Pied Piper, Inc",
        "teamSize": "1-10"
      },
      "unsubscribed": false,
    },
    "reward": {
      "conversionsRequired": 1,
      "couponCode": "LI_25_GIFT",
      "createdAt": 1542560101404,
      "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."
      },      
      "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
      "limit": 1,
      "isUnlimited": true,
      "numberOfWinners": 3,
      "title": "LinkedIn Post Mention",
      "id": "crew_xlj123",
      "metadata": {
        "foo": "bar",
        "amount": "$25",
        "points": 1000
      }
    },
    "campaign": {
      "id": "ct8f71",
      "name": "Pied Piper Advocate Program",
      "currencyISO": "USD",
      "rewards": [
        {
          "id" : "crew_xlj123",        
          "title": "LinkedIn Post Mention",          
          "conversionsRequired": 1,
          "couponCode": "LI_25_GIFT",
          "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>",
          "limit": 1,
          "isUnlimited": true,
          "limitDuration": "IN_TOTAL",
          "numberOfWinners": 3,
          "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."
          },      
          "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
          "metadata": {
            "foo": "bar",
            "amount": "$25",
            "points": 1000
          }      
        }
      ]
    }
  }
}
```

***

## `PARTICIPANT_REACHED_A_GOAL`

**Description:** When a participant unlocks a new reward

{% hint style="info" %}

### **Important notes:**

* **If you have manual reward approval enabled for your program, events will be sent twice: (1) when the reward is pending approval and (2) when the reward is approved.** To discern between unapproved/approved rewards, use the `data.reward.approved` property (approved rewards will have `approved` as `true`).
* The `data.reward` object contains combined data from the [`CampaignReward`](https://docs.loyaltysurf.io/integrations/rest-api/api-objects#reward) and [`ParticipantReward`](https://docs.loyaltysurf.io/integrations/rest-api/api-objects#participantreward).
  * `data.reward.rewardId` represents the ID of the `CampaignReward` and will always be the same. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward.
  * `data.reward.id` represents the ID of the `ParticipantReward` that was unlocked for the participant. This will be different for every new reward that the participant earns. You can find this ID by going to your admin dashboard and viewing the participant's rewards.
    {% endhint %}

```json
{
  "event": "PARTICIPANT_REACHED_A_GOAL",
  "createdAt": 1558345202613,
  "data": {
    "participant": {
      "id": "x9a7uu",
      "email": "richard@piedpiper.com",
      "firstName": "Richard",
      "lastName": "Hendricks",
      "notes": "",
      "rank": 9,
      "isWinner": true,
      "loyaltyActionCount": 11,
      "monthlyLoyaltyActionCount": 8,
      "prevMonthlyLoyaltyActionCount": 0,
      "createdAt": 1554431962667,
      "loyaltyActionSource": "DIRECT",
      "fraudRiskLevel": "LOW",
      "fraudReasonCode": "UNIQUE_IDENTITY",      
      "metadata": {
        "piedPiperUserId": "12a39-8aajd-1dwiq",
        "companyName": "Pied Piper, Inc",
        "teamSize": "1-10"
      },
      "unsubscribed": false,
    },
    "reward": {
      "approved": true,
      "conversionsRequired": 1,
      "couponCode": "LI_25_GIFT",
      "createdAt": 1542560101404,
      "approvedAt": 1659474941892,
      "fulfilledAt": null,
      "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."
      },      
      "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
      "limit": 1,
      "isUnlimited": true,
      "numberOfWinners": 3,      
      "title": "LinkedIn Post Mention",
      "rewardId": "crew_xlj123",
      "id" : "prew_ccm2ue",
      "participantId": "x9a7uu",
      "metadata": {
        "foo": "bar",
        "amount": "$25",
        "points": 1000
      }
    },
    "campaign": {
      "id": "ct8f71",
      "name": "Pied Piper Advocate Program",
      "currencyISO": "USD",
      "rewards": [
        {
          "id" : "crew_xlj123",        
          "title": "LinkedIn Post Mention",          
          "conversionsRequired": 1,
          "couponCode": "LI_25_GIFT",
          "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>",
          "limit": 1,
          "isUnlimited": true,
          "limitDuration": "IN_TOTAL",          
          "numberOfWinners": 3,          
          "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."
          },      
          "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
          "metadata": {
            "foo": "bar",
            "amount": "$25",
            "points": 1000
          }      
        }
      ]
    }    
  }
}
```

***

## `NEW_PARTICIPANT_ADDED`

**Description:** When a new participant is added to the program (via signups from the advocate portal, REST API, and manual adding/importing from the admin dashboard).

<pre class="language-json"><code class="lang-json">{
  "event": "NEW_PARTICIPANT_ADDED",
  "createdAt": 1558345215720,
  "data": {
    "id": "p88y0a",
    "email": "gavin.belson@hooli.com",
    "firstName": "Gavin",
    "lastName": "Belson",
    "notes": "This is obviously our competitor trying out our product!",
    "rank": 762,
    "isWinner": false,
    "loyaltyActionCount": 1,
    "monthlyLoyaltyActionCount": 0,
    "prevMonthlyLoyaltyActionCount": 0,
    "createdAt": 1554479231190,
    "loyaltyActionSource": "DIRECT",
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTITY",    
    "loyaltyActionCountPerReward": {
    },
    "metadata": {
      "piedPiperUserId": "au71p-121x9-88faa",
      "companyName": "Hooli, Inc",
      "teamSize": "10,000+"
    },
    "unsubscribed": false,
    "campaign": {
      "id": "ct8f71",
      "name": "Pied Piper Advocate Program",
      "currencyISO": "USD",
      "rewards": [
        {
          "id" : "crew_xlj123",        
          "title": "LinkedIn Post Mention",          
          "conversionsRequired": 1,
          "couponCode": "LI_25_GIFT",
          "description": "Make a LinkedIn post mentioning Pied Piper",
          "subdescription": "Post must be less than 1 week old from date of submission",
          "instructions": "&#x3C;div>&#x3C;p>&#x3C;strong>Helpful tips:&#x3C;/strong>&#x3C;/p>&#x3C;ul>&#x3C;li>Talk about how you used to do things before using Pied Piper&#x3C;/li>&#x3C;li>Mention specific ROIs (e.g, time saved, revenue generated)&#x3C;/li>&#x3C;/ul>&#x3C;/div>",
          "limit": 1,
          "isUnlimited": true,
          "limitDuration": "IN_TOTAL",
          "numberOfWinners": 3,              
          "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."
          },      
          "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
          "metadata": {
            "foo": "bar",
            "amount": "$25",
            "points": 1000
          }      
        }
      ]
    }    
<strong>  }
</strong>}
</code></pre>

***

## `PARTICIPANT_FRAUD_STATUS_UPDATED`

**Description:** When an existing participant's fraud status changes.

This webhook event is emitted if you manually mark a participant as a fraudster or non-fraudster from the LoyaltySurf admin dashboard. [Learn more here](https://support.loyaltysurf.io/article/419-how-does-loyaltysurfs-anti-fraud-system-work).

Here is an example of a `PARTICIPANT_FRAUD_STATUS_UPDATED` event where you can check the participant's fraud status via `data.participant.fraudRiskLevel` (it will be one of the following options: `"LOW"`, `"MEDIUM"`, or `"HIGH"`). You can also check the fraud reason code via `data.participant.fraudReasonCode` (see the [`Participant`](https://docs.loyaltysurf.io/developer-tools/rest-api/api-objects#participant) object for all fraud reason code options).

<pre class="language-json"><code class="lang-json">{
  "event": "PARTICIPANT_FRAUD_STATUS_UPDATED",
  "createdAt": 1558345215720,
  "data": {
    "participant": {
      "id": "p88y0a",
      "email": "gavin.belson@hooli.com",
      "firstName": "Gavin",
      "lastName": "Belson",
      "notes": "This is obviously our competitor trying out our product!",
      "rank": 762,
      "isWinner": false,
      "loyaltyActionCount": 1,
      "monthlyLoyaltyActionCount": 0,
      "prevMonthlyLoyaltyActionCount": 0,
      "createdAt": 1554479231190,
      "loyaltyActionSource": "DIRECT",
      "fraudRiskLevel": "LOW",
      "fraudReasonCode": "UNIQUE_IDENTITY",    
      "loyaltyActionCountPerReward": {
      },
      "metadata": {
        "piedPiperUserId": "au71p-121x9-88faa",
        "companyName": "Hooli, Inc",
        "teamSize": "10,000+"
      },
      "unsubscribed": false,
    },
    "campaign": {
      "id": "ct8f71",
      "name": "Pied Piper Advocate Program",
      "currencyISO": "USD",
      "rewards": [
        {
          "id" : "crew_xlj123",        
          "title": "LinkedIn Post Mention",          
          "conversionsRequired": 1,
          "couponCode": "LI_25_GIFT",
          "description": "Make a LinkedIn post mentioning Pied Piper",
          "subdescription": "Post must be less than 1 week old from date of submission",
          "instructions": "&#x3C;div>&#x3C;p>&#x3C;strong>Helpful tips:&#x3C;/strong>&#x3C;/p>&#x3C;ul>&#x3C;li>Talk about how you used to do things before using Pied Piper&#x3C;/li>&#x3C;li>Mention specific ROIs (e.g, time saved, revenue generated)&#x3C;/li>&#x3C;/ul>&#x3C;/div>",
          "limit": 1,
          "isUnlimited": true,
          "limitDuration": "IN_TOTAL",
          "numberOfWinners": 3,              
          "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."
          },      
          "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
          "metadata": {
            "foo": "bar",
            "amount": "$25",
            "points": 1000
          }      
        }
      ]
    }    
<strong>  }
</strong>}
</code></pre>

***

## `CAMPAIGN_ENDED`

**Description:** When the program ends.

{% hint style="info" %}
**Please note:** Only the first 1,000 will be returned in the `winners` Array.
{% endhint %}

```json
{
  "event": "CAMPAIGN_ENDED",
  "createdAt": 1558345152138,
  "data": {
    "id": "ct8f71",
    "name": "Pied Piper Advocate Program",
    "participantCount": 5661,
    "startedAt": 1522432573250,
    "endedAt": 1533532422153,
    "status": "COMPLETE",
    "loyaltyActionCount": 1673,
    "winnerCount": 1673,
    "winners": [
      {
        "id": "x9a7uu",
        "email": "richard@piedpiper.com",
        "firstName": "Richard",
        "lastName": "Hendricks",
        "notes": "",
        "rank": 9,
        "isWinner": true,
        "loyaltyActionCount": 11,
        "monthlyLoyaltyActionCount": 8,
        "prevMonthlyLoyaltyActionCount": 0,
        "createdAt": 1554431962667,
        "loyaltyActionSource": "DIRECT",
        "fraudRiskLevel": "LOW",
        "fraudReasonCode": "UNIQUE_IDENTITY",        
        "metadata": {
          "piedPiperUserId": "12a39-8aajd-1dwiq",
          "companyName": "Pied Piper, Inc",
          "teamSize": "1-10"
        },
        "unsubscribed": false,
      }
    ],
    "rewards": [
      {
        "id" : "crew_xlj123",        
        "title": "LinkedIn Post Mention",          
        "conversionsRequired": 1,
        "couponCode": "LI_25_GIFT",
        "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>",
        "limit": 1,
        "isUnlimited": true,
        "limitDuration": "IN_TOTAL",
        "numberOfWinners": 3,
        "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."
        },      
        "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
        "metadata": {
          "foo": "bar",
          "amount": "$25",
          "points": 1000
        }      
      }
    ]
  }
}
```