You can update reference set content and attributes. Reference sets store relational data like order history or subscription details that can be linked to contacts in your audience.

Typical use cases:

• Update order history with recent purchases, returns, and transaction details from your e-commerce platform.
• Synchronize subscription status updates including renewal dates, plan changes, and cancellations.

Preconditions

You have uploaded the CSV file to the SFTP server allocated to your Connect subscription. For instructions on setting up SFTP access, see Create a reference set.

Mutation structure

Example 1: Adding new records

Let's say your e-commerce platform processes thousands of orders daily. Each night, you export the day's transactions and import them to Connect, building a complete order history for each customer. This enables personalized campaigns based on purchase patterns, product recommendations, and win-back strategies for customers who haven't ordered recently.

Columns 1-6 from your file have been added to the reference set before.

Use the following mutation to import the file to Connect.

mutation ($importInput: ImportInput!) {
  createImportJob(importInput: $importInput) {
    id
  }
}

The mutation requires a JSON object.

{
  "importInput": {
    "dataSetId": "{REFERENCE_SET_ID}",
    "jobName": "Add new records 03-10-25",
    "importType": "ADD_UPDATE",
    "fileLocation": {
      "type": "SFTP",
      "filename": "orders-03-10-25.csv",
      "folder": "reference-sets"
    },
    "skipFirstRow": true,
    "mappings": [
      {
        "columnIndex": 1,
        "attributeName": "Order ID"
      },
      {
        "columnIndex": 2,
        "attributeName": "Client ID"
      },
      {
        "columnIndex": 3,
        "attributeName": "Amount"
      },
      {
        "columnIndex": 4,
        "attributeName": "Date"
      },
      {
        "columnIndex": 5,
        "attributeName": "First-time purchase"
      },
      {
        "columnIndex": 6,
        "attributeName": "Discount coupon"
      }
    ],
    "notifications": [
      {
        "channel": "EMAIL",
        "destination": "[email protected]"
      }
    ]
  }
}

Example 2: Creating new attributes during import

Imagine that your customer service team starts tracking return information (full refund, partial refund, or no return). You add the Return attribute to your order history reference set, enabling segmentation based on return behavior. This helps identify customers with frequent returns for quality follow-up or customers with no returns for loyalty rewards.

Note that you can import selected columns from the file. In the current example, we're skipping the "Discount coupon" column (column 6).

{
  "importInput": {
    "dataSetId": "{REFERENCE_SET_ID}",
    "jobName": "Add new attribute",
    "importType": "ADD_UPDATE",
    "fileLocation": {
      "type": "SFTP",
      "filename": "orders-new-data.csv",
      "folder": "reference-sets"
    },
    "skipFirstRow": true,
    "attributes": {
      "create": [
        {
          "name": "Return",
          "type": "TEXT"
        }
      ]
    },
    "mappings": [
      {
        "columnIndex": 1,
        "attributeName": "Order ID"
      },
      {
        "columnIndex": 2,
        "attributeName": "Client ID"
      },
      {
        "columnIndex": 3,
        "attributeName": "Amount"
      },
      {
        "columnIndex": 4,
        "attributeName": "Date"
      },
      {
        "columnIndex": 5,
        "attributeName": "First-time purchase"
      },
      {
        "columnIndex": 7,
        "attributeName": "Return"
      }
    ]
  }
}

Mutation arguments

• importInput (required): A JSON object with import settings.

Import input object

• attributes: Object - Use this object if your file contains new reference set attributes or if you want to update or remove existing attributes.
• dataSetId (required): String - The ID of the reference set that you are updating. If you don't have the IDs, see Query reference sets.
• fileLocation (required): Object - Use this object to locate the file on the FTP server.
• importType (required): Enum - The method of file processing. Valid value: ADD_UPDATE. The ADD_UPDATE method adds new records to an existing reference set and updates existing records.
• jobName (required): String - The name to assign to the import job.
• mappings (required): Array of objects - Create a separate object for each imported attribute.
• notifications: Array of objects - Create an object for each recipient you want to add.
• skipFirstRow: Boolean - Set the value to true if the file has a header row (default: false).

Attributes object

• create: Array of objects - Create new reference set attributes during import. Each object in the array supports the following fields:
  • decimalPrecision: Integer - The number of decimal places to display. Applies to numeric attributes.
  • name (required): String - Attribute name
  • type (required): Enum - The data type of the attribute. Valid values: TEXT, NUMBER, DATE, BOOLEAN.
• remove: Array of objects - Remove existing attributes from the reference set. Each object in the array supports the following field:
  • name (required): String - Attribute name
• update: Array of objects - Create new reference set attributes during import. Each object in the array supports the following field:
  • name (required): String - Attribute name

File location object

Used within the importInput object to specify where the CSV file is located.

• filename (required): String - The name and extension of the file.
• folder: String - The subfolder on the SFTP server where the file is located. If you have uploaded the file to the root folder, you don't need this field.
• type (required): Enum - The method of file delivery. Valid value: SFTP.

Mappings object

Used within the importInput object to map CSV columns to reference set attributes.

Both fields are required for each object in the array:

• attributeName (required): String - The name of the reference set attribute that the column from your CSV file will be mapped to.
• columnIndex (required): Integer - The index number of the column in the import file.

Notifications object

Used within the importInput object to configure job completion notifications.

• channel (required): Enum - Add this property if you want to receive a notification when the import job is complete. Valid value: EMAIL.
• destination (required): String - The email address for notification delivery.

Response fields

The mutation returns a JSON response containing:

• data (required): Object - Root response object.
  • createImportJob (required): Object - Type of operation performed.
    • id (required): String - The ID assigned to the import job. Use this ID to check the current job status in Connect (Data management > Job monitoring). You will get a configuration summary and a report on how many records have been processed.