# 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](https://support.cordial.com/hc/en-us/articles/115005528468-Supplements#supplementUse) or used to [build audience rules](https://support.cordial.com/hc/en-us/articles/115005528468-Supplements#searchSupplements) and [create analytics reports](https://support.cordial.com/hc/en-us/articles/115005528468-Supplements#analytics).

> **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](https://support.cordial.com/hc/en-us/articles/115005528468-Supplements#ui)
- [Via API](https://support.cordial.com/hc/en-us/articles/115005528468-Supplements#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](https://support.cordial.com/hc/en-us/articles/204570687-Supplements).

## 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](https://support.cordial.com/hc/en-us/articles/115005528468-Supplements#h_01GY0TJHTCKDXASEMAG71P2BW2) or added [via API](https://support.cordial.com/hc/en-us/articles/115005528468-Supplements#h_01G9QE5MYH4PB3GTRMCNE5K4XB) (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**](https://support.cordial.com/hc/en-us/articles/204570687-Supplements#postSuppImports) **:** Creates a supplement data import job of a CSV file containing supplement records.
- [**POST/supplements/{supplement}/records**](https://support.cordial.com/hc/en-us/articles/204570687-Supplements#postSuppRecords) **:** Creates a new data record in the specified supplement.
- [**PUT/supplements/{supplement}/records/{id}**](https://support.cordial.com/hc/en-us/articles/204570687-Supplements#putSuppRecordsId) **:** Updates an existing record in the specified supplement.

[Learn more about API methods for adding supplement records here](https://support.cordial.com/hc/en-us/articles/204570687-Supplements).

## 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](https://support.cordial.com/hc/en-us/articles/360043154271). 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](mailto: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**](https://support.cordial.com/hc/en-us/articles/204570687-Supplements#postSuppImports) 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](https://support.cordial.com/hc/en-us/articles/115005856748-Get-Supplements-getRecords-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](https://support.cordial.com/hc/en-us/articles/115005532168) and either visualized over time with [Audience Trend reports](https://support.cordial.com/hc/en-us/articles/115005364907), or used as filters for [Event Dashboards](https://support.cordial.com/hc/en-us/articles/115005533188) and [Event Reports](https://support.cordial.com/hc/en-us/articles/115005533268).

### Audience Trend reports

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

### Filter event dashboards

[Event dashboards](https://support.cordial.com/hc/en-us/articles/115005533188) 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](https://support.cordial.com/hc/en-us/articles/115005533268-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.