You can update reference sets using the createImportJob mutation. This lets you add new records, update existing records, create or remove attributes, and completely replace all data in the reference set.

Preconditions

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

Approaches to updating reference sets

When updating reference sets, you can choose between two import types that determine how your data is processed.

Approach A: Add and update records

Use the ADD_UPDATE import type to incrementally add new records or update existing ones. This approach preserves all records not included in your import file and allows you to modify the reference set structure by adding or removing attributes.

Best for:

• Daily order transactions or event logs where you're continuously adding new records.
• Updating specific records without affecting the rest of your data.
• Adding new attributes to track additional information.

Example: Your e-commerce platform processes orders throughout the day. Each night, you import the day's transactions to your order history reference set. Previous orders remain untouched while new orders are added, building a complete historical record.

Approach B: Replace all records

Use the REPLACE import type to completely refresh the reference set by removing all existing records and replacing them with the contents of your import file. The reference set structure remains unchanged.

Best for:

• Monthly or periodic complete data refreshes from source systems.
• Maintaining lists that should exactly match an external system (active coupons, current inventory).

Important restrictions when using REPLACE:

• All attributes defined in the reference set must be included in the mappings.
• Attribute operations (create, update, remove) are not allowed.
• Segment creation is not allowed.
• If at least one entry fails validation, the replacement doesn't happen and existing records are preserved.

Example: You maintain a discount coupons reference set. Each month, your promotions team exports the current active coupons list. Using REPLACE ensures your reference set contains only valid coupons. Expired codes are automatically removed and new seasonal offers appear.

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. Use the dataSets query to get the IDs of all reference sets in your subscription.
• delimiter: String - The type of delimiter used in the file. Valid values: ,, \t, |.
• fileFormat: Enum - File format. Valid value: DELIMITED.
• fileLocation (required): Object - Use this object to locate the file on the FTP server.
• importType (required): Enum - The method of file processing. Valid values: ADD_UPDATE, REPLACE.
• 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:
  • name (required): String - The name of the new attribute.
  • 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 - The name of the attribute to remove from the reference set.
• update: Array of objects - Update existing reference set attributes. Each object in the array supports the following field:
  • name (required): String - The name of the attribute to update.

File location object

Used within the importInput object to specify where the text 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, submit an empty value.
• type (required): Enum - The method of file delivery. Valid value: SFTP.

Mappings object

Used within the importInput object to map file 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 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.

Examples

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
  }
}

{
  "data": {
    "createImportJob": {
      "id": "1fbe6f9e-572e-4849-1111-00000x00000x"
    }
  }
}

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": "RS/Orders"
    },
    "skipFirstRow": true,
    "fileFormat": "DELIMITED",
    "delimiter": ",",
    "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]"
      }
    ]
  }
}

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": ""
    },
    "skipFirstRow": true,
    "fileFormat": "DELIMITED",
    "delimiter": ",",
    "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"
      }
    ]
  }
}

Replacing all records

A retail company maintains a discount coupons reference set for promotional campaigns. Every month, they create a fresh list of active coupons from their promotions management system, removing expired codes and adding new seasonal offers. Using the REPLACE import type ensures the reference set contains only currently valid coupons, preventing campaigns from displaying expired promotional codes to customers.

{
  "importInput": {
    "dataSetId": "{REFERENCE_SET_ID}",
    "jobName": "Replace discount coupons - September 2025",
    "importType": "REPLACE",
    "fileLocation": {
      "type": "SFTP",
      "filename": "active-coupons-09-2025.tsv",
      "folder": "RS/Coupons"
    },
    "skipFirstRow": true,
    "fileFormat": "DELIMITED",
    "delimiter": "\t",
    "mappings": [
      {
        "columnIndex": 1,
        "attributeName": "Coupon code"
      },
      {
        "columnIndex": 2,
        "attributeName": "Discount type"
      },
      {
        "columnIndex": 3,
        "attributeName": "Discount value"
      },
      {
        "columnIndex": 4,
        "attributeName": "Valid from"
      },
      {
        "columnIndex": 5,
        "attributeName": "Valid until"
      },
      {
        "columnIndex": 6,
        "attributeName": "Usage limit"
      }
    ],
    "notifications": [
      {
        "channel": "EMAIL",
        "destination": "[email protected]"
      }
    ]
  }
}

When to use each import type:

• Use ADD_UPDATE for incremental data like daily order transactions, subscription renewals, or customer support tickets where you're continuously adding new records.
• Use REPLACE for complete data refreshes like monthly active coupon lists, current inventory snapshots, or active subscription lists where you want the reference set to exactly match your source system.

👍

Important

When using the REPLACE option, follow the existing reference set structure. Make sure the mutation maps column headers to all existing reference set attributes. No attribute operations are allowed (adding, updating or removing).

Possible error messages

• INPUT_VALIDATION FAILED. The mappings have an attribute name that is not part of the data set definition. Please check the mapping attribute names and data set definition. You can get this error message while overwriting reference set content (the REPLACE import type). This import type doesn't allow adding new attributes or renaming existing ones.
• Invalid delimiter. Only the delimiters comma(,), tab(\t), or pipe(|) are allowed. - If you get this error, make sure the file uses only one of the supported delimiter types and repeat your request.