# Objects ## `Campaign` The `Campaign` Object contains detailed information about a LoyaltySurf program. | Name | Type | Description | | ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------- | | **id** | `string` | The unique identifier of the program | | **name** | `string` | The program name | | **loyaltyActionCount** | `integer` | The total loyalty action count | | **participantCount** | `integer` | The total participant count | | **winnerCount** | `integer` | The total number of winners†† | | **status** | `string` | The program status: `DRAFT`, `IN_PROGRESS`, `COMPLETE`, `DELETED` | | **currencyISO** | `string` | The program currency as a [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code (e.g, `USD`, `GBP`) | | **rewards** | `array` | The list of [Rewards](#reward) associated with the program | {% hint style="info" %} †† **Winners** = all participants with at least one approved reward. {% endhint %}
Campaign Object Example ```json { "id": "abc123", "name": "Pied Piper Advocate Program", "loyaltyActionCount": 121, "participantCount": 199, "winnerCount": 1, "status": "IN_PROGRESS", "rewards": [ { "id": "crew_xyz789", "title": "LinkedIn Post Mention", "description": "Make a LinkedIn post mentioning Pied Piper", "subdescription": "Post must be less than 1 week old from date of submission", "instructions": "

Helpful tips:

", "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." }, "conversionsRequired": 1, "isUnlimited": false, "limit": 1, "limitDuration": "IN_TOTAL", "numberOfWinners": 3, "order": 1, "couponCode": "PROMO_20_OFF", "imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png", "metadata": { "rewardForTierA": 50, "rewardForTierB": 100, "bonusPeriodMessage": "Offering 2x reward bonuses in our promotion period!" } } ] } ```
*** ## `Reward` The `Reward` Object (also known as `CampaignReward`) contains detailed reward information about a single reward for a program. {% hint style="info" %} **Note:** This `Reward` Object is different from a [`ParticipantReward`](#participantreward) Object, which is a reward earned by a participant. {% endhint %} | Name | Type | Description | | ---------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **id** | `string` |

The unique identifier of the program reward.

You can find this ID from Program Editor > 1. Rewards and clicking the reward.

| | **title** | `string` | The title of the program reward. Only used for internal purposes and never displayed to participants. | | **description** | `string` | A description of the reward | | s**ubdescription** | `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 | | **limitDuration** | `string` |

Whether the reward can be earned in total or on a monthly basis.

Options: "IN\_TOTAL", "PER\_MONTH"

| | **numberOfWinners** | `integer` | If `limitDuration` is `PER_MONTH`, this is the manimum number of total participants who can earn the reward in the given month. | | **couponCode** | `string` | A coupon code | | **imageUrl** | `string` | The reward image URL | | **order** | `integer` |

If there are multiple rewards, this represents the order in which the reward should be displayed.


This value is null by default, until set within the Design step of the program editor.

| | **metadata** | `object` | The reward metadata. |
Reward Object Example ```json { "id": "crew_xyz789", "title": "LinkedIn Post Mention", "description": "Make a LinkedIn post mentioning Pied Piper", "subdescription": "Post must be less than 1 week old from date of submission", "instructions": "

Helpful tips:

", "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." }, "conversionsRequired": 1, "isUnlimited": false, "limit": 1, "limitDuration": "IN_TOTAL", "numberOfWinners": 3, "order": 1, "couponCode": "PROMO_20_OFF", "imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png", "metadata": { "rewardForTierA": 50, "rewardForTierB": 100, "bonusPeriodMessage": "Offering 2x reward bonuses in our promotion period!" } } ```
*** ## `Participant` The `Participant` Object contains detailed information about a program participant. | Name | Type | Description | | --------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **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 program (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

- UNIQUE\_IDENTITY = They have a unique identity (no other participant has the same identity as them).
- DUPLICATE\_EMAIL = Their email is not unique, and is identical with another participant's email (e.g., = ).
- DUPLICATE\_IDENTITY
= Their identity is not unique, and matches that of another participant's.
SIMILAR\_EMAIL = Their browser fingerprint matches another participant's, and their email looks suspiciously similar (e.g., , )
- SIMILAR\_FIRST\_NAME = Their browser fingerprint matches another participant's, and their first name looks suspiciously similar.
- SIMILAR\_LAST\_NAME = Their browser fingerprint matches another participant's, and their last name looks suspiciously similar.
- MANUAL\_UPDATE = They were manually marked as a fraudster from the LoyaltySurf dashboard.
- WHITELISTED = They were allowed to join the program because one of their properties matched a whitelisted value.
- BLACKLIST\_MATCH = They were not allowed to join the program because one of their properties matched a blacklisted value.
- BLOCKED\_IP = They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.

| | **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 program 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 program: `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](https://app.loyaltysurf.io/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 program during the previous month.

|
Participant Object Example ```json { "id": "f8g9nl", "firstName": "Gavin", "lastName": "Belson", "loyaltyActionCount": 3, "monthlyLoyaltyActionCount": 3, "prevMonthlyLoyaltyActionCount": 0, "rank": 10001, "monthlyRank": 20001, "email": "gavin@hoolie.com", "createdAt": 1552404738928, "fraudRiskLevel": "LOW", "fraudReasonCode": "UNIQUE_IDENTIY", "isWinner": true, "loyaltyActionCountPerReward": { "crew_m5xm9l": 1, "crew_w01fil": 2 }, "monthlyLoyaltyActionCountPerReward": { "crew_m5xm9l": 1, "crew_w01fil": 2 }, "loyaltyActionSource": "DIRECT", "metadata": { "company": "Hooli, Inc", "companySize": 10000 }, "rewards": [ { "id": "prew_9x8v1b", "rewardId": "crew_m5xm9l", "status": "FULFILLED", "unread": true, "isAvailable": true, "approved": true, "isFulfilled": true }, { "id": "prew_vsdj34", "rewardId": "crew_w01fil", "status": "FULFILLED", "unread": true, "isAvailable": true, "approved": true, "isFulfilled": true }, { "id": "prew_sj3kap", "rewardId": "crew_w01fil", "status": "FULFILLED", "unread": true, "isAvailable": true, "approved": true, "isFulfilled": true } ] } ```
*** ## `ParticipantReward` The `ParticipantReward` Object represents a reward that the participant has earned. {% hint style="info" %} **Notes:** * This `ParticipantReward` Object is different from a program [`Reward`](#reward) Object and contains information that is only pertinent to the participant that earned the reward. * In [Webhooks](https://docs.loyaltysurf.io/integrations/webhooks), `ParticipantReward` Objects will also contain program `Reward` Object details. {% endhint %} | Name | Type | Description | | --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **id** | `string` |

The unique identifier of the participant's reward.

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.

| | **rewardId** | `string` | The ID of the [`CampaignReward`](#reward) that this participant has earned | | **status** | `string` | The status of the participant's reward: `PENDING`,`FULFILLED` | | **isAvailable** | `boolean` | `true` if the participant's reward is available for participant to claim or redeem | | **approved** | `boolean` | `true` if the participant's 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 ```json { "id": "prew_rr35mg", "rewardId": "crew_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. | Name | Type | Description | | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **id** | `string` | The unique identifier of the reward form submission | | **participantId** | `string` | The unique identifier of the [`Participant`](#participant) that submitted the form | | **participantEmail** | `string` | The email address of the [`Participant`](#participant) that submitted the form | | **rewardId** | `string` | The ID of the [`Reward`](https://docs.loyaltysurf.io/integrations/rest-api/api-objects#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 ```json { "id": "prfs_def678", "participantId": "f8g9nl", "participantEmail": "gavin@hoolie.com", "rewardId": "crew_xyz789", "status": "UNREVIEWED", "formData": { "linkedinPostUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b" } } ```
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.loyaltysurf.io/developer-tools/rest-api/api-objects.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.