Metadata

Use metadata to save any custom data to Participants and Rewards to make your referral program even more dynamic.

Certain GrowSurf objects, such as Participants and Rewards can have a special metadataparameter, 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.

• 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 campaign to retrieve later via the REST API when automating a reward via Webhooks or Zapier.

---

Overview

Participant metadata

• Can be set via the campaign editor, admin dashboard, REST API, JavaScript Web API, and embeddable elements

• 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 campaign editor

• Can be retrieved via JavaScript, REST API and is available via Webhooks

• Can be used in pre-populated social share and invite messages, and within GrowSurf emails

---

Participant metadata

Setting participant metadata

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

Campaign Editor

For referred participants:

From Campaign Editor > 5. Installation, navigate to the automagic form detection setup section (the page with the title "Choose forms from your site or web app to automatically track."). This form is for tracking referred people who came to your website through their friend's unique referral link.

Select a form and choose the input fields to save with each form submission. Any custom field that is not "Email", "First Name", or "Last Name" will be saved as metadata.

Choose the fields you want to save as metadata for referred participants

For referrers (your users/customers):

From Campaign Editor > 2. Design, you can update the Signup Form with custom fields. This signup form is intended for your users/customers who sign up to your referral program in order to refer their friends.

When a participant submits a new task from your referral portal, they will need to submit the custom fields as well, which will be saved as participant metadata.

Update the Signup Form in the campaign editor

When a participant signs up for the first time on your referral portal (or from the Embedded Signup Form), custom fields will be saved as metadata

Admin Dashboard

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

Update a participant in the admin dashboard

REST API

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

For adding new participants:

• /POST Add Participant

For updating existing participants:

• /POST Update Participant by ID

• /POST Update Participant by Email

JavaScript SDK

You can use the JavaScript method growsurf.addParticipant() to add metadata to a participant. Any keys other than email, firstName, and lastName will be saved as metadata. Metadata will only be set for new participants.

Example:

growsurf.addParticipant({
  email: '[e-mail]', 
  company: 'Hooli', 
  subscriptionPlan: 'businessPlan'
}).then(participant => {
  // handle participant
});

Note: Participant metadata cannot be updated using the JavaScript SDK. You must use the REST API to update metadata for existing participants.

Embeddable Elements

You can pass in custom participant values into any Embeddable Element using the data-grsf-metadata attribute. Metadata will only be set for new participants.

Example:

<div data-grsf-block-form
 data-grsf-email="[e-mail]"
 data-grsf-metadata="{'company': 'Hooli', ''subscriptionPlan': 'businessPlan'}"></div>

Note: Participant metadata cannot be updated using embeddable elements. You must use the REST API to update metadata for existing participants.

Using participant metadata

REST API

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

• /GET Participant by ID

• /GET Participant by Email

Webhooks

Participant metadata is returned on all participant payloads in Webhook events.

---

Reward metadata

Setting reward metadata

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

Add/edit reward metadata from the campaign editor

Using reward metadata

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

If you are using the JavaScript SDK, you can also retrieve reward metadata by calling growsurf.getCampaign(). This is useful for displaying any custom reward details in your UI.

---

Policies

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

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 GrowSurf, as metadata rewards are accessible from the JavaScript SDK.