# Metadata

Certain LoyaltySurf objects, such as [`Participants`](https://docs.loyaltysurf.io/developer-tools/rest-api/api-objects#participant) and [`Rewards`](https://docs.loyaltysurf.io/developer-tools/rest-api/api-objects#reward) can have a special `metadata` parameter, which is useful for storing any custom information.

## Use Cases

Here are some examples of how you could use `metadata`:

* Issue different reward values to participants based on their different `metadata` properties. [Learn more here](https://support.loyaltysurf.io/article/437-how-to-set-up-dynamic-rewards).
* If you need to save custom data to a participant to display or use later in your own application.
* Attach custom key/value data to rewards in your program to retrieve later via the REST API when automating a reward via Webhooks or Zapier.

***

## **Overview**

### **Participant metadata**

* Can be set via the program editor, admin dashboard, and REST API
* Can be retrieved via REST API and is available via Webhooks
* Can be viewed from your admin dashboard and when you download your participants list

### **Reward metadata**

* Can be set via the program editor
* Can be retrieved via REST API and is available via Webhooks
* Can be used within LoyaltySurf emails

***

## Participant metadata

### Setting participant metadata

There are several different ways to save metadata to a participant.

#### **Program Editor**

From *Program Editor > 2. Design*, you can update the Signup/Login Form with custom fields. When a participant submits a new task from your advocate portal, they will need to submit the custom fields as well, which will be saved as participant metadata.

<figure><img src="https://docs.loyaltysurf.io/~gitbook/image?url=https%3A%2F%2F3285719719-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FTwFF4MDnpq2eL5eyOdtK%252Fuploads%252FrCwGhwlLxnCc1ArFDOMN%252Fimage.png%3Falt%3Dmedia%26token%3D507878ec-2375-4a95-a6bb-cb8235c995da&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=ea2005aa&#x26;sv=2" alt=""><figcaption><p>Update the Signup/Login Form in the program editor</p></figcaption></figure>

<figure><img src="https://docs.loyaltysurf.io/~gitbook/image?url=https%3A%2F%2F3285719719-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FTwFF4MDnpq2eL5eyOdtK%252Fuploads%252FKfkqkCewggUpgGR5YzJD%252Fimage.png%3Falt%3Dmedia%26token%3D435adee3-1346-468a-9986-5839a7e6dafa&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=afc619bf&#x26;sv=2" alt=""><figcaption><p>When a participant signs up for the first time on your advocate portal, custom fields will be saved as metadata</p></figcaption></figure>

#### **Admin Dashboard**

When you are viewing a participant from the LoyaltySurf admin dashboard, you can add or update their metadata.

<figure><img src="https://docs.loyaltysurf.io/~gitbook/image?url=https%3A%2F%2F3285719719-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FTwFF4MDnpq2eL5eyOdtK%252Fuploads%252FCkUGOXJRqrNzETAOl5gA%252Fimage.png%3Falt%3Dmedia%26token%3D6d7bab21-19be-4869-b629-0ec888ed839a&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=66bfc208&#x26;sv=2" alt=""><figcaption><p>Update a participant in the admin dashboard</p></figcaption></figure>

#### **REST API**

You can use these REST API endpoints to add or update a participant's metadata:

**For adding new participants:**

* [`/POST Trigger Loyalty Action by Email`](https://docs.loyaltysurf.io/integrations/rest-api/api-reference#trigger-loyalty-action-by-email)
* [`/POST Add Participant`](https://docs.loyaltysurf.io/integrations/rest-api/api-reference#add-participant)

**For updating existing participants:**

* [`/POST Update Participant by ID`](https://docs.loyaltysurf.io/integrations/rest-api/api-reference#update-participant-by-id)
* [`/POST Update Participant by Email`](https://docs.loyaltysurf.io/integrations/rest-api/api-reference#update-participant-by-email)

### Using participant metadata

#### REST API

You can use these REST API endpoints to retrieve a participant's metadata:

* [`/GET Participant by ID`](https://docs.loyaltysurf.io/developer-tools/rest-api/api-reference#get-participant-by-id)
* [`/GET Participant by Email`](https://docs.loyaltysurf.io/developer-tools/rest-api/api-reference#get-participant-by-email)

#### Webhooks

Participant metadata is returned on all participant payloads in [Webhook events](https://docs.loyaltysurf.io/developer-tools/webhooks/events-reference).

***

## Reward metadata

### Setting reward metadata

There is only one way to update reward metadata, from *Program Editor > 1. Rewards*.

<figure><img src="https://docs.loyaltysurf.io/~gitbook/image?url=https%3A%2F%2F3285719719-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FTwFF4MDnpq2eL5eyOdtK%252Fuploads%252FF68Gn021GyDk7X1QuzxW%252Fimage.png%3Falt%3Dmedia%26token%3Df35eddc9-e060-4c8d-89b9-148adbaba077&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=15f0af35&#x26;sv=2" alt=""><figcaption><p>Add/edit reward metadata from the program editor</p></figcaption></figure>

### Using reward metadata <a href="#policies-1" id="policies-1"></a>

You can then reference this reward metadata in different places of the Program Editor for UI purposes. For example, metadata will be available as an option by clicking the "+ Personalize" dropdown in emails.

***

### Tutorial

View the following guide to help you add reward metadata and reference it throughout participant-facing elements of your LoyaltySurf program.

#### Webhooks

Reward metadata is returned on all `campaign` payloads in [Webhook events](https://docs.loyaltysurf.io/developer-tools/webhooks/events-reference). You can reference metadata when automating rewards using webhooks. This is useful so that your marketing team can make changes anytime to reward values in the future without getting developers involved.

<details>

<summary><strong>Guide to implementing reward metadata</strong></summary>

## 1. Add metadata to a reward

* Go to *Campaign Editor > 1. Rewards*.
* Open the reward you want to edit.
* Click "Advanced reward settings" and scroll to the Metadata section.
* Click "Add Metadata", and then enter `rewardForAdvocate` for the key, and `25` for the value.

<figure><img src="https://3285719719-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTwFF4MDnpq2eL5eyOdtK%2Fuploads%2FP3WxWZJdTcQYd86WoSOP%2FScreenshot_10.png?alt=media&#x26;token=641e96ed-7e68-4da9-bce9-d516c63a59bc" alt=""><figcaption></figcaption></figure>

***

## 2. Update campaign emails

* Go to *Campaign Editor > 3. Emails*.
* Open the "New Participant Reward Submission" email.
* In the Email Body section, type in `Once verified, you'll receive an email with instructions on how to redeem your $`
* Click the "+ Personalize" button, and from the dropdown select the reward metadata you added from step 1 above. Your text should now say something like this: `Once verified, you'll receive an email with instructions on how to redeem your ${{campaignReward['7w6ntg']['rewardForAdvocate']}}`
* Preview the changes on the right-side section to make sure everything is rendering properly. You should see your text rendering like this: `Once verified, you'll receive an email with instructions on how to redeem your $25`
* Repeat the above steps for all emails that you want to reference reward metadata in.

<figure><img src="https://3285719719-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTwFF4MDnpq2eL5eyOdtK%2Fuploads%2FF50efmHWLKmuceZ7s6Bm%2FScreenshot_9.png?alt=media&#x26;token=e50a6030-f305-4044-abce-682bfd30e2d3" alt=""><figcaption></figcaption></figure>

***

## 3. Final review and testing

Make sure to thoroughly [test your campaign](https://support.loyaltysurf.io/article/417-how-can-i-test-my-loyalty-program) to ensure that reward metadata displays correctly.

</details>

## Policies <a href="#policies-1" id="policies-1"></a>

The following are the policies when creating or updating metadata.

| Policy                  | Limit            |
| ----------------------- | ---------------- |
| **Metadata Key**        | 40 characters    |
| **Metadata Value**      | 500 characters   |
| **Total Metadata Keys** | 50 keys / object |
| **Key Characters**      | Alphanumeric     |

{% hint style="info" %}
**Note the following:**

* All metadata keys will be converted to camelCase. For example, if you provide a key "My Metadata Key" that key will be converted to `myMetadataKey` .
* **Important:** Do not store any sensitive information (personally identifiable information, such as credit cards and social security numbers) as metadata within LoyaltySurf, as metadata rewards are accessible from the JavaScript SDK.
  {% endhint %}