Supplements

Used for:

•  Message Content
•  Build an Audience

Supplement Overview

Supplements are data collections hosted in your Cordial account allowing you to store an unlimited number of records in a custom schema per your requirements. This data can be printed in a message or used to build audience rules.

Note: To build audiences using supplements, the feature must be enabled in your account. Please contact your Client Success Manager for more info.

For example, a business could have a supplement containing information related to its store locations:

• Store ID
• Store City
• Store Manager

A message could be sent to contacts containing all store locations.

While supplement data is independent of contacts and their attributes, it can be related to a contact through a common key or data attribute. This will allow you to use filtered supplement data results in a message.

For example, a contact could have an attribute of Store ID that relates it to the store supplement collection. Then a message could be sent with store information filtered by the Store ID for each contact.

Supplements offer a way to store structured objects of data per each contact that don’t fit well into attributes, lists or orders.

Some other examples would be using supplements to store nights booked at a hotel or banks of coupon codes.

How Supplements Are Stored

Supplements are stored in Cordial as JSON objects.  Below is an example of how supplement records are stored in JSON:

[
   {
   "id": "0",
    "storeid": "123",
    "city": "Phoenix",
    "manager": "John Doe",
    "ct": "2017-03-23T18:24:53+0000",
    "lm": "2017-03-23T18:24:53+0000"
   },
   {
    "id": "1",  
    "storeid": "124",
    "state": "CA",
    "manager": "Jane Doe",
    "ct": "2017-03-23T17:42:21+0000",
    "lm": "2017-03-23T17:45:18+0000"
   }
]
	

When supplement records are added, Cordial automatically creates additional data about the supplement:

• ct: Date Created
• lm: Date Last Modified

Creating a Supplement Collection

Before adding supplement records, a supplement collection must be created. There are 2 ways to create a supplement collection:

• Via the UI
• Via the API

Creating a Supplement Via the UI

1. Log into the Cordial platform and navigate to Data › Supplement Data.
2. Click the button New.
   
   
3. Fill out the fields:
   • Name: The name the supplement will be referred to in the UI.
   • Key: A unique name that will be referenced in messages and the API. No spaces or special characters are allowed.
   • Indexes: Fields within supplement records that are searchable and referenced in messages. At least one index field must be created. Supplement record index values cannot be empty.
     
     Note: Additional non-indexed field values can be added via the API. These non-indexed fields are available for message content, but not available for searching or filtering via Smarty.

Creating a Supplement Via the API

Cordial also allows creation of supplement collections via the API using the POST /supplements method.

Learn more about creating supplement collections via the API.

Adding Supplement Records

Once a supplement collection is created you are able to add records to the collection. Records can be added via the API one at a time or imported in bulk in a CSV document.

  Watch the video about importing supplement data.

Supplement records are added via the API using the following methods:

• POST /supplements/{supplement}/imports
  Creates a supplement data import job of a CSV file containing supplement records.
  
  
• POST /supplements/{supplement}/records
  Creates a new data record in the specified supplement.
  
  
• PUT /supplements/{supplement}/records/{id}
  Updates an existing record in the specified supplement.

Learn more about the API methods for adding supplement records.

Building Audience Rules Using Supplement Data

You are able to create audience rules based on supplement data.

1. Create a new supplement collection and check the option "Use as a contact attribute".
   
2. Create indexes for each of the fields that you would like to be searchable when building audience rules.
   
   Note: While email or cID is required in the data file, it should not be included as an indexed field.
3. Import your data file using the POST /supplements/{supplement}/imports method.
   
   Note: Each record in the data file must contain a cID or email (as well as a unique ID).
4. When building audiences, choose the Supplement rule, select the supplement and add any conditions to define the rule.
   

Using Supplements in a Message

Supplement data can be rendered in a message using the Smarty getRecords method. You are able to query supplement data, filter it according to certain rules, and then render it in message content for each contact.

Learn more about rendering supplement data using Smarty.