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.
• Make sure all contacts are reachable by email or phone. Contacts with no contact information won't be imported.
• 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. Do not use null, N/A or any other values. If you leave the field blank for a contact, their status for the Email channel will be automatically set to OPT_IN.

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. 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 contacts.
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: 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": "Contact Key"
      },
      {
        "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

The mutation contains the importInput argument at the root level.

Required properties

Properties required by the importInput object:

Properties supported by the fileLocation object:

Properties supported by objects within the mappings array (both of them are required):

Optional properties

Additional properties supported by the importInput object:

Properties supported by the consent object (all of them are optional):

Properties nested into the channels object

Properties nested into the consentGroups object

Fields required by the notifications object

Fields

Fields returned by the createImportJob mutation:

How contacts are handled

When you import contacts from a file, Connect makes sure that each contact has at least one addressable attribute assigned (email or phone number). If a contact isn't reachable, it won't be imported to the audience and an error report will be created in Job monitoring.

Then the system compares reachable contacts to the contacts that are already present in your audience. The key attribute and addressable attributes play the primary role in the processing.

Case A: existing key

If a key is present in the audience, the system updates all values for this contact based on the file.

Case B: new key

If a new key is detected, the system looks at addressable attributes.

Existing addressable attribute detected

If Connect finds a contact with the same email address or phone number, it checks the possibility of overwriting its data using information from the imported file.

• If the contact in the audience doesn't have a key assigned, it acquires the key from the import file. All other attributes are also updated based on the file.
• If the contact in the audience has a key assigned, then a new contact is created in the audience. This is because existing contact keys cannot be overwritten.

All addressable attributes are new

If the email address and phone number from the file aren't present in the audience, a new contact is created.

📘

Note

If your audience doesn't use contact keys, then Connect fully relies on addressable attributes.