You can import CSV files with contact data to your audience. This option lets you add new contacts, update existing ones and create segments based on imported contacts.

Only the columns that you map to existing contact attributes are imported to the audience. The Consent column is mapped separately within the consent object.

File requirements

• Maximum size - 5 GB
• Format - CSV, comma-separated
• Encoding - UTF-8
• 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. If the + symbol is missing before a phone number, it will be added automatically in Connect.
• The header row is optional.
• 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 CSV files in Excel as it can automatically convert a date like02/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.

Approaches to consent management

When you are adding new contacts to the audience, it is important to set proper consent statuses that reflect people's willingness (or refusal) to receive communications from your company.

You can take one of the following approaches when importing contacts from a file.

Approach A: apply the same status to all

You can set a common consent status to all contacts using the status property. Here is an example for the Email channel.

{
  "consent": {
    "channels": {
      "channel": "EMAIL",
      "status": "OPT_IN_UNVERIFIED"
    }
  }
}

If your marketing team manages consent on the consent group basis, use the consentGroups property instead of channels. The common status will be effective within the consent group you specify.

{
  "consent": {
    "consentGroups": {
      "consentGroupId": "97660d76-02d8-5fd6-1aa1-000000000000",
      "status": "OPT_IN_UNVERIFIED"
    }
  }
}

To get the IDs of available consent groups, use the dataSets query. For more information about it, see Query an audience.

query {
  dataSets {
    nodes {
      consentGroups {
        name
        id
      }
    }
  }
}

{
  "data": {
    "dataSets": {
      "nodes": [
        {
          "consentGroups": [
            {
              "name": "Newsletters",
              "id": "97660d76-02d8-5fd6-1aa1-000000000000"
            },
            {
              "name": "Promotions",
              "id": "97660d76-02d8-5fd6-1aa1-000000000000"
            },
            {
              "name": "Information",
              "id": "97660d76-02d8-5fd6-1aa1-000000000000"
            },
            {
              "name": "Custom",
              "id": "97660d76-02d8-5fd6-1aa1-000000000000"
            }
          ]
        }
      ]
    }
  }
}

🚧

Important

When submitting consent preferences, use either consent groups or channels in your mutation. Using both at the same time would result in an error.

Approach B: import statuses from a file

You can import a current consent status for each contact. If you choose to follow this approach, you must add the Consent column to the file and provide one of the following values for each contact: OPT_IN, OPT_IN_UNVERIFIED or OPT_OUT. If a person's consent status is unknown, leave the field blank. Do not use null, N/A or any other values.

Here is an example for the Email channel. It means that column 6 in the CSV file has consent statuses for the Email channel.

{
  "consent": {
    "channels": {
      "channel": "EMAIL",
      "columnIndex": 6
    }
  }
}

If your marketing team manages consent on the consent group basis, use the consentGroups property instead of channels. The following example means that column 6 in the CSV file has consent statuses for the specified consent group.

{
  "consent": {
    "consentGroups": {
      "consentGroupId": "97660d76-02d8-5fd6-1aa1-000000000000",
      "columnIndex": 6
    }
  }
}

Approach C: ignore consent settings

If you omit the consent property, all new contacts will be automatically opted in to the Email channel. The statuses of existing contacts will stay unchanged.

Initial setup

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

1. Run the following command in your terminal emulator.

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

2. Find two files in your user folder: a private key (key) and a public key (key.pub).
3. Log in to your Acoustic Connect account, click on your user icon in the upper-right corner and then select Edit profile.

4. Scroll down to the SSH Key section and upload your key.pub file there.

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

6. Navigate to the directory allocated for your subscription.
7. (optional) Create a sub-directory for contacts.
8. 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: the email address that you sign in to Acoustic Connect with. The length of the email address must be within 3-100 characters. It can contain Latin letters (lower- and uppercase), numbers from 0 to 9, underscores (_), hyphens (-) and periods (.). AWS doesn't allow any other characters such as plus (+) or quotes (" "). It won't be possible to establish a connection if the email address doesn't meet their requirements.

Mutation structure

Example

Let's say you have uploaded the following contact data to the SFTP server.

Use the following mutation to import the file to Connect.

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

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

The mutation requires a JSON object.

{
  "importInput": {
    "dataSetId": "a4112ecf-3514-4393-a5b2-00000000",
    "jobName": "Import new contacts",
    "importType": "ADD_UPDATE",
    "createSegment": false,
    "fileLocation": {
      "type": "SFTP",
      "filename": "prospects-03-05-2025.csv",
      "folder": "contacts"
    },
    "consent": {
      "enableOverrideExistingOptOut": false,
      "channels": {
        "channel": "EMAIL",
        "status": "OPT_IN_UNVERIFIED"
      }
    },
    "skipFirstRow": true,
    "mappings": [
      {
        "columnIndex": 1,
        "attributeName": "Prospect ID"
      },
      {
        "columnIndex": 2,
        "attributeName": "Email"
      },
      {
        "columnIndex": 3,
        "attributeName": "First Name"
      },
      {
        "columnIndex": 4,
        "attributeName": "Last Name"
      },
      {
        "columnIndex": 5,
        "attributeName": "Phone Number"
      },
      {
        "columnIndex": 6,
        "attributeName": "Last Order"
      }
    ]
  }
}

Arguments

Arguments required by the createImportJob mutation:

Properties supported by the importInput object

Properties nested into the consentGroups object

Properties nested into the channels object

Fields

Fields returned by the createImportJob mutation: