How can we help?

Overview

Supplements are data collections hosted in your Cordial account that allow you to store an unlimited number of records in a custom schema. Supplements provide a flexible mechanism for storing structured data objects that don't fit well into contact attributes, lists, or orders. Supplement data can be rendered in a message or used to build audience rules and create analytics reports.

Use case
You could use a supplement to store information related to your brick-and-mortar locations. Fields in the supplement might be the following:

• Store ID
• Store city
• Store manager

Supplement records are often related to a contact through a common key or data attribute. This association allows you to use filtered supplement data in a message. For example, a contact attribute could be created to hold a Store ID value for each contact. The Store ID value in the contact attribute would correspond with the Store ID field in the store supplement collection.

How Cordial stores supplements

Below is an example of a supplement stored in Cordial as a JSON object.

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

When supplement records are added, Cordial automatically creates additional fields to hold metadata about the supplement:

• ct: Date Created
• lm: Date Last Modified

When adding supplement records, each record must be given a unique ID. Supplement IDs cannot be 24-character hex strings. This is a platform-reserved format.

Create a supplement collection

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

• Via the UI
• Via API

When a supplement index field is passed, its data type (string, integer, etc.) will be recognized and searchable in the Cordial UI. If the field data type is changed, any new supplement values for that field will not be searchable in the UI. It is necessary to create a new field with the updated data type to make the values searchable in the platform UI.

Create a supplement collection in the UI

1. Log in to the Cordial platform and navigate to Data > Supplement Data on the left sidebar.
2. Click the New button at the top of the Supplements page.
3. Fill out the required fields:

• Name: This will be seen in the UI as a friendly reference for the supplement.
• Key: A unique name that will be referenced in messages and API calls. No spaces or special characters are allowed.
• Description: An optional description field, allowing users to add notes for easier reference.
• Indexes: Fields within supplement records that are searchable and referenced in messages. Indexes should match the column headers of your CSV file—but only index headers you need to be searchable.

1.) At least one index field must be created. 2.) Supplement record index values cannot be empty. 3.) Individual supplement record index values cannot exceed 1024 bytes. 4.) Certain special characters may be interpreted as Boolean operators when stored within indexed fields, which can cause supplement data query failures. We recommend altogether omitting special characters from indexed field data. 5.) The following system-reserved index keys cannot be used as supplement index field names: id, _id, lm, ct.

Sparse index functionality

The sparse index functionality allows you to define a data type and enable querying without requiring a value for that index. Unique indexes function the same way as an implicit record id would. The value of that field is unique and only one record may exist.

If you have a unique id already, or multiple unique indexes, the combination of all uniquely constrained indexes AND the implicit id index must ALL be unique for the record.

Example

A supplement has three indexes:

• id - the implicit record identifier, which must be unique
• product_name - a standard required value string index
• And product_type - a sparse string index

You can load data like this:

id,product_name,product_type
1,jeans,pants
2,flannel,shirt
3,cardigan,sweater
4,leather,belt

And still query on product_type even though some records don't have values:

{$get_products.key = 'product_data'}
{$get_products.query.product_type = 'pants'}
{$get_products.limit = 10}
{$get_products.sort = []}
{$get_products.cacheMinutes = 0}
{$get_products.data = $utils-getSupplementRecords($get_products.key, $get_products.query,

Create a supplement collection via API

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

• You can learn more about creating supplement collections via API here.

Edit supplements

1. Once you've successfully created a supplement, navigate to Data > Supplement Data and locate the supplement.
2. From the Details tab, click Edit.
3. Make the desired changes and click Update Supplement.

View supplement records

1. To view all records attached to a supplement, select the Records tab.
2. Click any record to view it in JSON format.

Add and import supplement records

After you create a supplement collection, you can add and import records to the collection. Records can be imported via data job in the UI or added via API (one at a time or in bulk).

In CSV format

model,brand,price,milage,image,id
pilot,honda,33000,100000,http://www.example.com/image1.png,1
explorer,ford,34000,39000,http://www.example.com/image2.png,2
prius,toyota,27000,66000,http://www.example.com/image3.png,3

• Each record in the import file must have a unique id value, which is stored as a string.
• The id column header must be in lower case.
• Values under column headers that have not been indexed, such as image header, will be added as strings.

Add arrays

In addition to strings, numbers, and dates, you can upload an array of comma-separated values within the supplement record.

Use case
You might have an array of values for automobile color. Because array values are separated by commas, they need to be escaped by double quotes to avoid errors while uploading the CSV file. Your data file might look like the following examples.

In CSV format

"[""gray"",""sky blue"", ""true blue""]"
"[""green"",""silver"",""electric yellow""]"
"[""red"",""tan"",""gold""]"

Import supplement records in the UI

Cordial's UI makes it simple to import supplement records via data job.

1. Log in to Cordial and navigate to Data Jobs > Create New Data Job.
2. Under Import, select Supplements.
3. Fill in the Name and Tags fields. For Type, choose either One-time or Recurring. Assign a Priority for the job and click Continue.
4. From the Data Job creation page, click Edit in the Data Source pane. Choose the Data Location. For our example, we'll use a local CSV file. Click Continue and follow the prompt to upload the file.
5. Under Data Mapping, choose the desired Import option:

• Insert new records and update existing records
• Only update existing records (ignore new records)
• Only insert new records (ignore existing records)

6. Map your data file columns to the appropriate attributes.
7. Choose whether or not to trigger any actions as a result of your import.
8. If the job is recurring, click Recurring on the left sidebar and configure the desired settings in the Schedule pane.
9. In the On Completion pane, enter an email address where you'd like to receive a notification when the job is complete.
10. Click the Run Data Job button on the left.

Add and import supplement records via API

Supplement records are added via 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 API methods for adding supplement records here.

Build audience rules using supplement data

You can create audience rules based on supplement records that are used as contact attributes. Contact attribute supplements are associated with individual contact records using the unique contact identifier. For this reason, import files that are updating contact attribute supplements must contain a contact identifier column such as cID, email, or a custom contact identifier key used in your account.

To use this feature, it must be enabled in your account. Please submit a support ticket or send an email to support@cordial.com to request this feature.

1. From the Cordial Dashboard, navigate to Data > Supplement Data.
2. Select New on the Supplements page to create a new supplement collection.
3. On the Create Supplement pane, select the option Use as a contact attribute.
4. Create indexes for each of the fields that you want to be searchable via Smarty.
5. Import your data file using the POST/supplements/{supplement}/imports method.
6. To build a new audience, navigate to Contacts > Audiences and select New.
7. In the Audience Builder, choose the Supplement rule and drag the desired supplement into your audience.
8. Add Conditions to define the rule.

Use supplements in a message

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

Build analytics reports using supplements

Audiences based on supplements can be saved as audience rules and either visualized over time with Audience Trend reports, or used as filters for Event Dashboards and Event Reports.

Audience Trend reports

To access Audience Trend reports, log in to Cordial and navigate to Analytics > Audience Trends.

Filter event dashboards

Event dashboards provide a way to visualize event activity over time by creating customizable charts. You can take advantage of supplement data in event dashboard charts using audience filters.

Filter event data reports

Event data reports—navigation: Analytics > Event Data Reports—allow you to view reports of event activity. You can filter reports using audience rules much the same as event dashboards.

Export supplements

You can export supplement records in the UI via data job. There are endless possibilities to easily pull highly specific and relevant supplement data.

1. Log in to Cordial and navigate to Data Jobs > Create New Data Job.
2. Under Export, select Supplements.
3. Fill in the Name and Tags fields. For Type, choose either One-time or Recurring. Assign a Priority for the job and click Continue.
4. From the Data Job creation page, click Edit in the Data Source pane to specify the supplements you want to export.
5. In the Supplements pane, configure the supplements you'd like to export: specify the actual Supplements and click + Add Conditions for more specificity on the data you're exporting.
6. Select Edit under Data Mapping and enter the required fields:

• Export name: give your export a unique name consisting only of letters and numbers
• Export file name: give your export file a unique name consisting only of letters and numbers
• Export file type: choose CSV or JSONL
• Column key(s): specify the column key(s) to use in your exported file
• Check the Header box to include a header row in your exported file
• Select whether to Compress file(s) or Split file per chunks. If splitting the file, specify the amount of records to appear in each file.

7. Select Edit under Data Destination and choose the destination for your exported supplements file. You can select Local, FTP, SFTP, AWS S3 bucket, Google Cloud, or Azure Blob.
8. In the On Completion pane, enter an email address where you'd like to receive a notification once the job is complete. This step is optional.
9. If your data job is recurring, Publish the data job then select Recurring under Settings on the left. From here, set the Schedule for your data job and then Enable it.
10. Run the export events data job. Once completed, you can find the job under the Jobs widget.