You can update reference sets in the following ways:

Add new records
Update existing records
Add attributes
Remove existing attributes

In the upcoming versions, we will make it possible to update existing attributes.

Preconditions

You have uploaded the CSV file to the SFTP server allocated to your Connect subscription. For instructions, see Import reference sets.

Example

Let's say you want to add recent order history records to a reference set in Connect. Columns 1-6 have been added to the reference set before. Column 7 (Return) is a new one.

Order ID	Client ID	Amount	Date	First-time purchase	Discount coupon	Return
8789645	HC-2190012	671.70	2024-11-03T16:04:38Z	FALSE	FRIENDS	N/A
8158122	HD-92590022	349.00	2024-11-03T16:04:38Z	FALSE	WELCOME	Full
8259627	HX-51900938	650.67	2024-11-03T15:03:24Z	FALSE	N/A	Partial
8134985	HX-25900860	59.20	2024-11-02T22:15:38Z	FALSE	WELCOME	N/A
8548972	HE-37810560	76.29	2024-11-02T19:39:55Z	FALSE	N/A	N/A
8991467	HA-22100109	2040.80	2024-11-02T20:26:13Z	FALSE	N/A	N/A
8614432	HE-00500445	5360.29	2024-11-02T17:09:56Z	FALSE	N/A	Partial
8881448	HM-28811560	830.60	2024-11-02T12:35:05Z	FALSE	N/A	N/A

Mutation structure

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

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

The mutation requires a JSON object. Here is an example if we import columns 1-6 from our sample file with order history.

{
  "importInput": {
    "dataSetId": "3603cf4a-5708-478c-1111-0000000000",
    "jobName": "Add new records 03-11-24",
    "importType": "ADD_UPDATE",
    "fileLocation": {
      "type": "SFTP",
      "filename": "orders-10-31-24.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]"
      }
    ]
  }
}

To import column 7 (Return), you must create an attribute for it within the same mutation.

{
  "importInput": {
    "dataSetId": "3603cf4a-5708-478c-1111-0000000000",
    "importType": "ADD_UPDATE",
    "jobName": "Add new attribute",
    "fileLocation": {
      "type": "SFTP",
      "filename": "orders-new-data.csv",
      "folder": "reference-sets"
    },
    "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"
      },
      {
        "columnIndex": 7,
        "attributeName": "Return"
      }
    ],
    "attributes": {
      "create": [
        {
          "name": "Return",
          "type": "TEXT"
        }
      ]
    }
  }
}

Arguments

Arguments required by the createImportJob mutation:

Argument	Values	Definition
`importInput`	`$importInput`	A JSON object with import settings

Parameters supported by the importInput object

Field	Nested field	Values	Required?	Definition
`attributes`	`create`	Array of objects	Optional	Create an object for each new column you want to import. The column headers will be converted to attributes in Connect.
	`remove`	Array of objects	Optional	Create an object for each column that you want to remove from the reference set.
`dataSetId`		ID	Required	The ID of the reference set that you are updating. - If the reference set is connected to the audience, you can get its ID using the Get connected reference sets mutation. - If the reference set isn't connected to the audience, copy its ID from the Connect UI.
`fileLocation`	`filename`	String	Required	The name and extension of the file
	`folder`	String	Required	The folder or subfolder on the SFTP server where the file is located
	`type`	`SFTP`	Required	The method of file delivery
`importType`		`ADD_UPDATE`	Required	The method of file processing. The `ADD_UPDATE` method adds new data to an existing reference set.
`jobName`		String	Required	The name you want to assign to the import job
`mappings`		Array of objects	Required	Create an object for each column you want to import to Connect.
`notifications`	`channel`	`EMAIL`	Optional	The media channel to send the notification through. Skip this field if you don't want to receive a notification when the import job is complete.
	`destination`	String	Optional	The email address for notification delivery. Skip this field if you don't want to receive a notification.
`skipFirstRow`		Boolean. Default value - `false`.	Optional	Set the value to `true` if the file has a header row.

Input fields supported by objects within the create field

Field	Values	Required?	Definition
`decimalPrecision`	Integer	Optional	For numeric attributes, you can specify the number of decimal places after the separator.
`name`	String	Required	The name of the attribute
`type`	One of the following values: - `TEXT` - `NUMBER` - `BOOLEAN` - `DATE`	Required	The data format of the attribute

Input fields supported by objects within the remove field

Field	Values	Required	Definition
`name`	String	Required	The name of the attribute to remove from the reference set.

Input fields supported by objects within the mappings field

Field	Values	Required?	Definition
`attributeName`	String	Required	The name of the attribute in the reference set that the column will be mapped to
`columnHeader`	String	Optional	The name of the column in the import file. If you choose to identify the column using `columnHeader`, do not submit the `columnIndex` value (it would result in a conflict).
`columnIndex`	Integer	Optional	The index number of the column in the import file. If you choose to identify the column using `columnIndex`, do not submit the `columnHeader` value (it would result in a conflict).

Fields

Fields returned by the createImportJob mutation

Field	Values	Definition
`id`	ID	The ID assigned to the import job