GrowSurf Docs
Help CenterSystem StatusContact SupportYour Dashboard →
  • Welcome
  • Getting Started for Web
    • Google Tag Manager
    • Participant Auto Authentication
  • Getting Started for Native Mobile
  • Developer Tools
    • Embeddable Elements
    • JavaScript SDK
      • Tutorials
      • Single Page Applications
      • API Reference
    • REST API
      • Tutorials
      • Objects
      • API Reference
      • API Guidelines
      • API Response Codes
    • Webhooks
      • Securing Your Webhooks (optional)
      • Examples
      • Events Reference
    • Metadata
  • Integrations
    • ActiveCampaign
      • Tutorials
    • Amplitude
    • AWeber
      • Tutorials
    • Brevo (formerly Sendinblue)
      • Tutorials
    • Cal.com
    • Calendly
    • Campaign Monitor
      • Tutorials
    • Chargebee
    • Constant Contact
      • Tutorials
    • ConvertKit
      • Tutorials
    • Customer.io
      • Tutorials
    • Drip
      • Tutorials
    • EmailOctopus
      • Tutorials
    • Fullstory
    • GetResponse
      • Tutorials
    • Google Ads
    • Google Analytics
    • Heap
    • Help Scout
    • HubSpot
      • Tutorials
    • Intercom
      • Tutorials
    • Klaviyo
      • Tutorials
    • LinkedIn Ads
    • Mailchimp
      • Tutorials
    • MailerLite
      • Tutorials
    • Mailjet
      • Tutorials
    • Make
      • Tutorials
    • Marketo
      • Tutorials
    • Meta (Facebook) Ads
    • Mixpanel
    • Pabbly Connect
      • Tutorials
    • PayPal
    • Pendo
    • PostHog
    • Recurly
    • Salesforce
      • Tutorials
    • Segment
    • SendGrid
      • Tutorials
    • Slack
    • Stripe
    • Tango Card
    • Typeform
    • X (Twitter) Ads
    • Zapier
      • Tutorials
      • Using Filters
      • Troubleshooting
Powered by GitBook
On this page
  • Use Cases
  • Overview
  • Participant metadata
  • Reward metadata
  • Participant metadata
  • Setting participant metadata
  • Using participant metadata
  • Reward metadata
  • Setting reward metadata
  • Using reward metadata
  • Tutorial
  • Policies

Was this helpful?

  1. Developer Tools

Metadata

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

Last updated 1 month ago

Was this helpful?

Certain GrowSurf objects, such as and 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. .

  • 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.

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.

Admin Dashboard

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

REST API

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

For adding new participants:

For updating existing participants:

JavaScript SDK

Example:

growsurf.addParticipant({
  email: 'gavin@hooli.com', 
  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

Example:

<div data-grsf-block-form
 data-grsf-email="gavin@hooli.com"
 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:

Webhooks


Reward metadata

Setting reward metadata

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

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.

JavaScript

Webhooks


Tutorial

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

Guide to implementing reward metadata

1. Add metadata to a reward

  • Go to Campaign Editor > 1. Rewards and click the Continue button.

  • Open the reward you want to edit.

  • Click "Advanced reward settings" and scroll to the Metadata section.

  • Click "Add Metadata", and enter rewardForReferrer for the key, and 50 for the value.

  • Click "Add Metadata" again, and enter rewardForReferred for the key, and 50 for the value.


2. Update campaign design

  • Go to Campaign Editor > 3. Design.

  • Here are the sections you'll want to update with reward metadata:

    • Header Content

    • Share (Social & Email Invites)

    • Referred Friend Motivators (Welcome Banner and Inline Welcome Message)

  • For each element in the sections above, click the "+ Personalize" button underneath each input field, and from the dropdown select the reward metadata you added from step 1 above. See the images below as examples.

Header Content

To explain this first example: The text Sign up for Subank and receive ${{campaignReward['p6k82i']['rewardForReferrer']}}! will be rendered as Sign up for Subank and receive $50!.

Share

After you add reward metadata to a share message, see how it renders by clicking on the corresponding share button in the live preview section of the campaign editor.

Referred Friend Motivators

To explain this example, the {{referrerName}} invited you to join Subank! Sign up today and get ${{campaignReward['p6k82i']['rewardForReferred']}}! will be rendered as Gavin B invited you to join Subank! Sign up today and get $50!.


3. Update campaign emails

  • Go to Campaign Editor > 3. Emails.

  • Open the "New Participant Reward" email.

  • In the Email Body section, type in the following: {{isReferrer ? ("You've just earned a $" + campaignReward["p6k82i"]["rewardForReferrer"] + " gift card for referring a friend!") : ("You just got a $" + campaignReward["p6k82i"]["rewardForReferred"] + " gift card for activating your account and making your first purchase!") }}

  • Preview the changes on the right-side section to make sure everything is rendering properly.

    • For referrers, the text would render like this: You've just earned a $50 gift card for referring a friend!.

    • For referred friends, the text would render like this: You just got a $50 gift card for activating your account and making your first purchase!

  • Repeat the above steps for all emails that you want to reference reward metadata in.

    • Note: For other emails, you can simply click the "+ Personalize" button to insert reward metadata. The "New Participant Reward" email is the only special email type to use the {{isReferrer ? ... : ... }} syntax for in order to account for when emails are sent to both referrers and referred friends (when the reward won is a double-sided reward).


4. Final review and testing

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.

Choose the fields you want to save as metadata for referred participants
Update the Signup Form in the campaign editor
When a participant signs up for the first time on your referral portal (or from the ), custom fields will be saved as metadata
Update a participant in the admin dashboard

You can use the JavaScript method 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.

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

Participant metadata is returned on all participant payloads in .

Add/edit reward metadata from the campaign editor

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

Reward metadata is returned on all campaign payloads in . 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.

Make sure to thoroughly by signing up as both the referrer and a referred friend to ensure the reward metadata displays correctly in different elements.

Participants
Rewards
Learn more here
/POST Add Participant
/POST Update Participant by ID
/POST Update Participant by Email
growsurf.addParticipant()
Embeddable Element
/GET Participant by ID
/GET Participant by Email
Webhook events
growsurf.getCampaign()
Webhook events
test your campaign
Embedded Signup Form