LoyaltySurf Docs
Help CenterSystem StatusContact SupportYour Dashboard →
  • Welcome
  • Tutorials
  • Developer Tools
    • REST API
      • Tutorials
      • Objects
      • API Reference
      • API Guidelines
      • API Response Codes
    • Webhooks
      • Securing Your Webhooks (optional)
      • Examples
      • Events Reference
    • Metadata
  • Integrations
    • Chargebee
    • HubSpot
    • PayPal
    • Recurly
    • Slack
    • Stripe
    • Tango Card
    • Zapier
      • Tutorials
      • 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 advocate program even more dynamic.

PreviousEvents ReferenceNextChargebee

Last updated 27 days ago

Was this helpful?

Certain LoyaltySurf 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, 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 campaign 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.

Campaign Editor

From Campaign 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.

Admin Dashboard

When you are viewing a participant from the LoyaltySurf 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:

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


Tutorial

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

Webhooks

Guide to implementing reward metadata

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.


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.


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

Update the Signup/Login Form in the campaign editor
When a participant signs up for the first time on your advocate portal, custom fields will be saved as metadata
Update a participant in the admin dashboard

Participant metadata is returned on all participant payloads in .

Add/edit reward metadata from the campaign editor

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 to ensure that reward metadata displays correctly.

Participants
Rewards
Learn more here
/POST Trigger Loyalty Action by Email
/POST Add Participant
/POST Update Participant by ID
/POST Update Participant by Email
/GET Participant by ID
/GET Participant by Email
Webhook events
Webhook events
test your campaign