Reference sets store relational data like order history or subscription details that can be linked to contacts in your audience. You can create reference sets by importing plain text files to your Connect subscription.

Typical use cases:

• Import order history to track customer purchases, returns, and transaction patterns for personalized product recommendations.
• Store subscription records including plan types, renewal dates, and billing information for lifecycle marketing.
• Track customer support tickets with case details, resolution status, and response times for service quality analysis.

Limitations

• Default limit: 5 reference sets per subscription
• Extended limit: up to 25 reference sets (available on request)

File requirements

Your file must meet these specifications:

• Encoding: UTF-8
• Format: CSV (comma-separated), PSV or TSV. The same type of delimiter must be used throughout the file. If the file contains mixed delimiters or other separating characters, the import job may fail.
• Header row: Optional
• Maximum size: 5 GB

Phone numbers

If a file contains phone numbers, they must be formatted according to the ISO E.164 standard: +[country code][area code][phone number].

No spaces, dashes, or special characters are allowed.

Dates

If a file contains dates, they must be in one of the following formats:

• YEAR_MONTH_DAY_DASH_SEPARATED_WITH_TIME (default)
• YEAR_MONTH_DAY_DASH_SEPARATED_WITH_TIME_AND_MS
• YEAR_MONTH_DAY_DASH_SEPARATED
• MONTH_DAY_YEAR_SLASH_SEPARATED
• DAY_MONTH_YEAR_SLASH_SEPARATED
• YEAR_MONTH_DAY_SLASH_SEPARATED
• DAY_MONTH_YEAR_DOT_SEPARATED

Initial setup

You can upload your file two ways:

• SFTP: Configure access to your Connect FTP directory (if you haven't done it yet) and upload your files there.
• Web upload: request a preSignedUploadURL, upload the file to it, then reference it in the import job.

Mutation arguments

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

Import input object

Only importType, jobName, and fileLocation are required. mappings and attributes are optional.

• attributes: Object - Defines the structure of the reference set by creating attributes from the columns in your file.
• createSegment: Boolean - Set to true if a segment should be created once the import completes (default: false).
• dataSetName: String - The name you want to assign to the new reference set. Requirements: up to 25 characters, Latin letters, numbers 0-9, hyphens (-) and underscores (_). Not required when updating an existing reference set.
• dataSetType (required when importType is CREATE): Enum - The type of data set you are importing. Valid value: REFERENCE_SET.
• dateFormat: Enum - Add this property if your file contains dates and their format isn't YEAR_MONTH_DAY_DASH_SEPARATED_WITH_TIME. Valid values: YEAR_MONTH_DAY_DASH_SEPARATED_WITH_TIME (default), YEAR_MONTH_DAY_DASH_SEPARATED_WITH_TIME_AND_MS, YEAR_MONTH_DAY_DASH_SEPARATED, MONTH_DAY_YEAR_SLASH_SEPARATED, DAY_MONTH_YEAR_SLASH_SEPARATED, YEAR_MONTH_DAY_SLASH_SEPARATED, DAY_MONTH_YEAR_DOT_SEPARATED.
• delimiter: String - The type of delimiter used in the file (valid values: ,, \t and | ).
• fileFormat: Enum - File format. Valid values: DELIMITED (default), JSONL.
• fileLocation (required): Object - Use this object to locate the file on the FTP server, or reference a web-uploaded file.
• importType (required): Enum - The method of file processing. Valid values: CREATE, ADD_UPDATE, DELETE, REPLACE. The CREATE method creates a reference set in your Connect subscription, adds attributes (column headers) and rows to it.
• into: Enum - Indicates where the import will be stored.
• jobName (required): String - The name you want to assign to the import job.
• mappings: Array of objects - Create a separate object for each column you want to import to Connect.
• notifications: Array of objects - Create an object for each recipient you want to add.
• overwriteEmptyFields: Boolean - Controls whether empty or null values in the import file overwrite existing attribute data. When false (default), existing values are preserved if the import cell is empty. When true, empty or null values overwrite existing data.
• segmentName: String - The name of the segment to create. Used together with createSegment.
• skipFirstRow: Boolean - Set the value to true if the file has a header row (default: false).

Attributes object

Used within the importInput object to define the reference set structure.

• create (required): Array of objects - Create an object for each column you want to import. The column headers will be converted to attributes in Connect. The header that uniquely identifies the rows must be marked as the key. Each object in the array supports the following fields:
  • identifyAs: Object - Use this object to mark the key column that uniquely identifies the rows.
    • key: Boolean - Set to true to mark this attribute as the key.
  • name (required): String - The name of the attribute.
  • type (required): Enum - The data format of the attribute. Valid values: TEXT, NUMBER, BOOLEAN, DATE, GEOSPATIAL, JSON, ARRAY.

File location object

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

• filename: String - The name and extension of the file. Required for SFTP uploads.
• 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. Required for SFTP uploads.
• contentId: String - For web uploads, the content ID returned by preSignedUploadURL.
• type (required): Enum - The method of file delivery. Valid values: SFTP, WEB_UPLOAD.

Mappings object

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

• attributeName: String - The name of the attribute in the reference set that the column will be mapped to.
• columnIndex: Integer - The index number of the column in the import file.
• transform: Object - Optional transform to apply to this field during import. Accepts either ac-rules format ({ type, config }) or MongoDB-style syntax (e.g. { "$toUpper": "$field" }).

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.

Example

Let's say an e-commerce company creates an order history reference set to track all customer purchases. Each order is uniquely identified by Order ID (marked as the key attribute), while Client ID links orders to contacts in the audience. This enables segmentation based on purchase behavior, such as targeting customers who used specific discount coupons or identifying first-time buyers for welcome campaigns.

We upload the file to the server and then run a mutation to import the file to Connect.

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

{
  "data": {
    "createImportJob": {
      "id": "{JOB_ID}"
    }
  }
}

The mutation requires a JSON object.

{
  "importInput": {
    "dataSetName": "Orders",
    "dataSetType": "REFERENCE_SET",
    "attributes": {
      "create": [
        {
          "name": "Order ID",
          "type": "TEXT",
          "identifyAs": {
            "key": true
          }
        },
        {
          "name": "Client ID",
          "type": "TEXT"
        },
        {
          "name": "Amount",
          "type": "NUMBER"
        },
        {
          "name": "Date",
          "type": "DATE"
        },
        {
          "name": "First-time purchase",
          "type": "BOOLEAN"
        },
        {
          "name": "Discount coupon",
          "type": "TEXT"
        }
      ]
    },
    "jobName": "Add orders",
    "importType": "CREATE",
    "fileFormat": "DELIMITED",
    "delimiter": ",",
    "dateFormat": "DAY_MONTH_YEAR_SLASH_SEPARATED",
    "fileLocation": {
      "type": "SFTP",
      "filename": "orders.csv",
      "folder": "RS/Orders"
    },
    "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"
      }
    ]
  }
}

Possible error messages

• S3_FILE_METADATA_FAILED. - Make sure the file name is correct and it's accessible on the FTP server through the specified path. Repeat your request after that.
• INPUT_VALIDATION_FAILED. 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.

Further steps

When the import job is complete, you can connect the reference set to the audience or to another reference set. For instructions, see Connect reference sets.