Setting up Direct Import

Direct import allows you to programmatically import contacts contained in a .csv file into the platform by posting a form with various parameters.

About this task

Warning: Setting up direct import requires some programming knowledge.

For example, if you have a .csv file containing a group of contacts that you want to add to Bronto, you can upload these contacts via a form without having to log in. These contacts can be added to a specific list and their data can be mapped to corresponding contact fields in your account.

After you run an import, you can view the details of the contact import by going to Reports > Downloads and clicking on a Report Name in the Contact Import Report Downloads table to download a contact import report. For more information see Legacy Report Downloads Page.

Direct import supports the use of commas and tabs as delimiters and embedded quotes must be escaped.

Procedure

  1. Go to Settings > Platform Settings > Data Exchange.
  2. Scroll down to the Direct Import section.
  3. Make note of the URL and parameters displayed.
    This information will be needed in order for direct import to work properly.
    Parameter Name Parameter Description Required Or Optional Default Description
    site_id Site/Account ID Required Your site/account id will be a unique number displayed on the Data Exchange page in the Direct Import section.
    user_id User ID Required Your user id will be a unique number displayed on the Data Exchange page in the Direct Import section.
    key Authentication Token Required The authentication token will be a unique string displayed on the Data Exchange page in the Direct Import section.
    Warning: This is not the same as an API token.
    filename Name Of The File Required The contact file contents to be processed, including the required header row.
    format File Format Required Specify csv, tab or txt for the file format.
    source Source Of The Contacts Required Specify the source that the contacts were obtained from.
    Tip: If a source is provided, it will appear on the Contact Details for that contact. For more information, see Contact Details General Information.
    action Action To Take Optional addupdate Specify add, update, addupdate, addupdate_transactional or contact_status_in_file for the action.
    • add: Create new contacts. If the contact already exists, a new record will not be created.
    • update: Update an existing contacts. This is the only way to change an email address. New contacts are ignored.
    • addupdate: Add or update contacts. If the contact does not exist, a new record is created. If a field is specified but the value is left blank, the field will be cleared of its value.
    • addupdate_transactional: Add or update contacts while preserving transactional status. If the contact does not exist, a new records is created. If a field is specified but the value is left blank, the field will be cleared of its value. Transactional status is not changed.
    • contact_status_in_file: Indicates whether you have specified the contact status in the import file. When this action is set, the import will look at the contact_status column for the contact status values to import. Contacts assigned the active or onboarding status will have the onboarding status until they have completed the automated onboarding process.
    listname List Name Optional <no list> Specify the name of the list to add the contacts to. If the list name does not exist, it will be created.
    email Notification Email Address Optional <no email> The email address to send the confirmation report to.
    contact_status Contact Status Optional The contact status indicates whether you can send marketing emails to a contact and the level of engagement you have with a contact. Acceptable values are:
    • active
    • onboarding
    • transactional
    • unconfirmed
    • unsubscribed or unsub
    Other values for contact status will be ignored. Contacts assigned the active or onboarding status will have the onboarding status until they have completed the automated onboarding process.
    consent_date Consent Date Optional The date of the last change or addition to the consent log for the contact. Accepts only the date format yyyy-mm-dd. You can see the existing Consent Date for a contact by exporting all site consent records or exporting a single contact's consent records.
    consent_ip_address Consent IP Address Optional The IP address that is associated with a consent record.You can see the existing Consent IP Address for a contact by exporting all site consent records or exporting a single contact's consent records.
    fileCharacterEncoding Character Set Encoding Optional UTF-8 or ISO-8859-1 Allows you to specify a character set encoding to apply to your direct import. Acceptable values are:
    • UTF-8 For UTF-8
    • ISO-8859-1 For Latin-1
    • UTF-16 For UTF-16
    • UTF-16BE For UTF-16 Big Endian
    • UTF-16LE For UTF-16 Little Endian
    • US-ASCII For ASCII

    If you do not specify the fileCharacterEncoding, Bronto will attempt to import and validate the imported data as UTF-8. If Bronto determines that the file was not using UTF-8, the platform will then import the file(s) using ISO-8859-1 (Latin 1). This does not guarantee the files are using the ISO-8859-1 (Latin 1) character set. You should look at the contact data you imported to make sure it was stored as expected. Pay particularly close attention to any special characters your data may have, such as é.

    inAppAlertMode Sets Platform Alert Preferences Optional none Indicates whether you want to receive an alert in Bronto when the import finishes. The alert will contains details about the success or failure of the direct import. Acceptable values are:
    • none No alert will be sent; this is true even if there are failures with the import
    • user An alert will only be sent to the Bronto user who was associated with the direct import
    • site All users on the site will receive the alert
    preserveTransactional Locks Transactional Status Optional False When you include this parameter the status of existing transactional contacts included in the import will not change. By default, a direct import will change a contact's status from transactional to onboarding unless you include this parameter. Unless your import is meant to change the status for these contacts because they opted-in, you should use this parameter as part of any import that includes existing transactional contacts.
    Note: The parameter names and values are case sensitive and should be lowercase.
  4. Using the URL and parameter information obtained from the previous step, post the data to your account. There are several ways to accomplish this task. One method is to use curl.
    1. Create a contacts.csv file on your desktop. You can also include contacts fields using the name of each field in a separate column with its value. Your file should be less than 110 MB.
    2. Retrieve your copied values for site_id, user_id, and key from Settings > Platform Settings > Data Exchange.
    3. Update this curl statement.
      • Replace MY_SOURCE_VALUE with your contact source.
      • Replace /PATH/TO/FILE with the path on your computer to your import file.
      • Replace MY_SITE_ID with your site ID (Example: 39116).
      • Replace MY_USER_ID with your user ID (Example: 63011).
      • Replace MY_LIST_NAME with your list name. This needs to be the name of an existing list.
      • Replace MY_KEY with your authentication token.
      curl -F 'source="MY_SOURCE_VALUE"' -F 'filename=@/PATH/TO/FILE/contacts.csv' -F 'format=csv' -F 'fileCharacterEncoding=ISO-8859-1' -F 'site_id=MY_SITE_ID' -F 'user_id=MY_USER_ID' -F 'listname= MY_LIST_NAME' -F 'key=MY_KEY' http://app.bronto.com/mail/subscriber_upload/index/
    4. Paste and run your curl statement from your computer in a terminal.
    Note: There are a few mistakes that could cause an import to fail. For example, specifying the wrong character set or wrong file format. Also, if you are uploading a CSV file, the heading for the email column must be email.
  5. An import summary report can be viewed by going to Reports > Downloads.
    Additionally, an email will be sent if you specified an email address to be notified when the import is finished.