Import contacts from CSV

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. 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.
ssh-keygen -t ed25519 -C "Acoustic.com - Connect key" -f key
  1. Find two files in your user folder: a private key (key) and a public key (key.pub).
  2. Log in to your Acoustic Connect account, click on your user icon in the upper-right corner and then select Edit profile.
Access to profile editing
  1. Scroll down to the SSH Key section and upload your key.pub file there.
  1. Create a new connection in an FTP client such as FileZilla. The settings are described below.
Site Manager in FileZilla
  1. Navigate to the directory allocated for your subscription.
  2. (optional) Create a sub-directory for contacts.
  3. 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

Connect domainSFTP host
prod-us-east-1s-acca2da9ec374c47b.server.transfer.us-east-1.amazonaws.com
prod-eu-central-1s-0f495b8f35324396a.server.transfer.eu-central-1.amazonaws.com
prod-ap-southeast-2s-9596192dde684690a.server.transfer.ap-southeast-2.amazonaws.com

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.

Contact KeyEmailFirst NameLast NamePhone NumberLast Order
ESX3845[email protected]KateReese+915555512342022-02-01T16:04:38Z
RUT8175[email protected]MaximilianTsiolkovsky+374555512342024-06-01T16:04:30Z
BBA0627[email protected]AmaliaAhmed+23555512342024-11-01T16:04:38Z
ESX4985[email protected]Antonio
BBN8971[email protected]JillianS.+375555512342025-11-01T16:04:38Z
PPO4467[email protected]ChrisJr.

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.

ArgumentValuesDefinition
importInput$importInputA JSON object with import settings

Required properties

Properties required by the importInput object:

PropertyValuesDefinition
createSegmentBooleanLets you create a segment based on the imported contacts. The segment will be available as soon as the import job is complete.
dataSetId String The ID of your audience
fileLocation Object Use this object to locate the file on the FTP server.
jobName StringThe name you want to assign to the import job
importType Enumeration. Valid value:ADD_UPDATEThe method of file processing.

The ADD_UPDATE method lets you add new contacts to the audience and update existing ones.
mappings Array of objects Create a separate object for each imported attribute.

Properties supported by the fileLocation object:

PropertyValuesRequired?Definition
filenameStringRequiredThe name and extension of the file
folderStringOptionalThe subfolder on the SFTP server where the file is located.

💡If you have uploaded the file to the root folder, do not use this field.
typeEnumeration. Valid value - SFTP.RequiredThe method of file delivery

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

PropertyValuesDefinition
attributeNameStringThe name of the contact attribute in the audience that the column from your CSV file will be mapped to.

⚠️ If your audience uses contact keys, you must map the key attribute to a file column name.
columnIndexIntegerThe index number of the column in the import file.

Optional properties

Additional properties supported by the importInput object:

PropertyValuesDefinition
consentObjectConsent settings for the contacts
dateFormatEnumeration. 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
Add this property if your file contains dates and their format isn't YYYY-MM-DDTHH:mm:ssZ.
notificationsArray of objects Create an object for each recipient you want to add.
segmentNameStringIf you set createSegment to true, you must assign a name to the new segment.
skipFirstRow Boolean. Default value - false. Set the value to true if the file has a header row.

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

PropertyValuesDefinition
channelsObjectUse this object to submit consent statuses for a particular media channel.

⚠️ channels cannot be used together with consentGroups in the same mutation.
consentGroupsObjectUse this object to submit consent statuses for a particular consent group.

⚠️ consentGroups cannot be used together with channels in the same mutation.
enableOverrideExistingOptOutBoolean. Default value - false.Set the value to true to allow overwriting the OPT_OUT statuses of existing contacts who previously unsubscribed from receiving communications.

Properties nested into the channels object

PropertyValuesRequired?Definition
channelEnumeration. Valid values:

- EMAIL
- SMS
- WHATSAPP
Required The type of communication channel
columnIndexIntegerOptionalThe number of the Consent column in your file.

⚠️ If you submit this property, do not use the status property in the same mutation.
statusEnumeration. Valid values:

- OPT_IN,
- OPT_IN_UNVERIFIED
- OPT_OUT
Optional Use this field to set a common consent status within the channel for all contacts in the import file.

⚠️ If you submit this property, do not map any consent-related columns to the audience using columnIndex.

Properties nested into the consentGroups object

PropertyValuesRequired?Definition
columnIndexInteger OptionalThe number of the Consent column in your file.

⚠️ If you submit this property, do not use the status property in the same mutation.
consentGroupIdStringRequiredThe ID of a consent group in your audience
statusEnumeration. Valid values:

- OPT_IN,
- OPT_IN_UNVERIFIED
- OPT_OUT
OptionalUse this field to set a common consent status within the consent group for all contacts in the import file.

⚠️ If you submit this property, do not map any consent-related columns to the audience using columnIndex.

Fields required by the notifications object

FieldValuesDefinition
channelEnumeration. Valid value - EMAIL.Add this property if you want to receive a notification when the import job is complete.
destinationStringThe email address for notification delivery

Fields

Fields returned by the createImportJob mutation:

FieldValuesDefinition
idIDThe 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.

How contacts are handled

When you import contacts from a file, the system compares them to the contacts that are already present in your audience. The key attribute plays 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.

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.

No addressable attributes detected

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.