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:

• YYYY-MM-DD
• MM/DD/YYYY
• DD/MM/YYYY
• YYYY/MM/DD
• DD.MM.YYYY
• YYYY-MM-DDTHH:mm:ssZ

👍

Tip

Be careful when opening text files in Excel as it can automatically convert a date like 02/10/2025 to an unsupported format such as 2/10/25. To prevent this, use a text editing app such as Notepad or Visual Studio Code.

Initial setup

To start importing reference sets, you need to establish access to our SFTP server.

1. Run the following command in your terminal emulator. Feel free to replace "Acoustic Connect key" with another unique name.

ssh-keygen -t ed25519 -C "Acoustic Connect key" -f key

2. Navigate to the directory from which you ran the command and find two new files there: a private key (key) and a public key (key.pub).

🚧

Warning

For security reasons, don't share the private key with anyone.

3. Run the following mutation to register your public key in our API. Replace "YOUR_PUBLIC_KEY" with the content from key.pub.

mutation updatePublicKey {
  updatePublicKeyForConnectUser(
    publicKey: "{YOUR_PUBLIC_KEY}"
  ) {
    publicKey
  }
}

{
  "data": {
    "updatePublicKeyForConnectUser": {
      "publicKey": "{YOUR_PUBLIC_KEY}"
    }
  }
}

4. Create a new connection in an FTP client such as FileZilla. The settings are described below.

5. Navigate to the directory allocated for your subscription.
6. (optional) Create a sub-directory for reference sets.
7. Upload your files.

📘

Note

When the import job is completed, the files will be deleted from the SFTP server.

Settings for the SFTP connection

Host

Use a host associated with your Connect domain

Other settings

• Protocol: SFTP – SSH File Transfer Protocol
• Port: 22
• Logon type: key file
• Key file: Specify a path to the private key file on your hard drive.
• User: Your Acoustic Connect email address
  • Requirements: 3-100 characters, Latin letters, numbers 0-9, underscores (_), hyphens (-), periods (.)
  • Not allowed: plus (+), quotes ("), or other special characters

Mutation arguments

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

Import input object

• attributes (required): Object - Defines the structure of the reference set by creating attributes from the columns in your file.
• dataSetName (required): 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 (_).
• dataSetType (required): 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 YYYY-MM-DDTHH:mm:ssZ. Valid values: YEAR_MONTH_DAY_DASH_SEPARATED_WITH_TIME (default), 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 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 value: CREATE. The CREATE method creates a reference set in your Connect subscription, adds attributes (column headers) and rows to it.
• jobName (required): String - The name you want to assign to the import job.
• mappings (required): 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.
• 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.

File location object

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

• filename (required): String - The name and extension of the file.
• folder (required): 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 attribute in the reference set that the column 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.

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.