Import and update of contacts by CSV

You can import and update contacts using a CSV file. This allows you to create new contacts, update your existing ones, or enrich the contact data such as by applying labels to a group of contacts. 

The actual import is done manually through the Engage UI and below you will learn how to prepare for and manage the import.

Before you start

Make sure your file meets the following requirements:

• The file format is .CSV with UTF-8 encoding
• The number of rows is less than 50 000
• You have exactly one row per contact
• There is a header row with column (field) names
• You are using semicolon (;) as separator (recommended)

Prepare your CSV file

To prepare your file:

• Remove any duplicate contacts before starting the import
• Check your column names are descriptive and consistent
• Ensure your data matches the correct format for each field
• Confirm the file contains only contacts of the same contact type
• It is also recommended to add a column for labels to identify imported contacts

File size

The maximum size of a file in a single contact CSV import depends on the number of rows (contacts) as well as the number of columns (fields). A file with a thousand rows and only two columns will be very different in size from one with the same number of rows but twenty columns. 

There really is no minimum number of rows although files containing only a few or a single contact (rows) should not be imported this way, and should use the API or file-based transfer instead.

Fields

Some commonly used fields in a CSV contacts import are:

Here is further information concerning certain common fields:

mobilePhone: This should always begin with a country calling code preceded by + (+46, +47…). If the country calling code is not defined, it will be assumes that the phone number is from the country defined in the Engage backend of your environment (Module settings → SMS).

socialSecurityNumber: If you are using the default settings for the attribute then the length of this can be either 12 digits or 10, with or without hyphen.

gender: It is not necessary to specify gender if the file contains a socialSecurityNumber attribute since this will tell Engage the gender of the customer.

birthDay: The format should be 8 digits with hyphens (ex. 1995-12-01). This field is connected to the age field and will set the age of the customer automatically if these are both used.

currentStoreId: If used this should have the externalId value of the store. When importing the current store, Engage automatically sets the registered-in store to this value as well. The column name for the current store must end with “Id“ (for example "storeId", "currentStoreId").

Further important points are:

• If a contact attribute is mandatory it must exist in your CSV and have a value
• Whatever key value you are using in your Engage setup must exist in the import file. The exception to this is when the key value is of type "sequence" (memberNumber). In this case, Engage will automatically set a value for each contact in the file when the import is done.

Doing the import

Now the file is ready and it's time to import it. Follow these steps:

1. Upload your file

1. Go to Contacts > Import/Export > Import
2. Upload your .CSV file

2. Configure file settings

• Select the Contact type for the contacts in your file
• Confirm file encoding (UTF-8 is recommended)
• Check the file preview to ensure data looks correct

3. Map fields

• Now map each column in your CSV file to a field in Engage
• Resolve any unmapped fields manually

4. Choose import method

Now select how contacts should be handled:

• Create and update: Create new contacts and update existing ones
• Only create new contacts: Only add new contacts
• Only update: Only update existing contacts

5. Review and start import

• Review the import summary

6. Finalize

• Decide if you want any contacts created to trigger automations that start with the "New contact registered" trigger
• Select "Import" to start the import

7. After the import

Once the import completed, you’ll see a summary showing:

• Number of contacts created
• Number of contacts updated

You can now use filters or labels to find the imported contacts.

Error handling

Here the are the most common sources of error in an import:

Duplicated values error

When your file is uploaded to Engage, it is processed internally in smaller parts know as batches. This concept is important when it comes to understanding duplicate errors.

On import, your CSV file is checked to see if any values defined as unique (email or phone number, for example) are duplicated. In this context, "duplicated" can mean one of two things:

• Two or more rows in the CSV contain the same value for a unique field
• A unique field in the CSV has the same value as an existing contact (when creating contacts)

What happens next depends on how many of these duplicate values have been found.

If the number of duplicates found is greater than 5 the whole batch will fail. A log will then be sent to the integration log, containing information on the field, value and contact type.

If the number of duplicates is 5 or less the file will continue to be imported. However, the rows flagged as containing duplicate values will be ignored in the import.

Validation error

If a validation error occurs for a value in the import (the value has the wrong type, or contains invalid characters, or is required but empty) the invalid value is just ignored and the import continues.

Handling large files

If your file exceeds the recommended size limit (which is 50 000 rows) you will need to split it into smaller CSV files before import. When you do this, be sure the same header row exists in each file.

One way to do this is with a python script such as this one:

import csv
import os

def create_batches(input_file, output_folder, batch_size):
    # Create output folder if it doesn't exist
    if not os.path.exists(output_folder):
        os.makedirs(output_folder)

    with open(input_file, 'r', newline='') as csvfile:
        reader = csv.reader(csvfile)
        header = next(reader)

        batch_number = 1
        batch_count = 0
        output_csv = None

        for i, row in enumerate(reader):
            if i % batch_size == 0:
                if output_csv:
                    output_csv.close()
                output_file = os.path.join(output_folder, f'batch_{batch_number}.csv')
                output_csv = open(output_file, 'w', newline='')
                writer = csv.writer(output_csv)
                writer.writerow(header)
                batch_number += 1
                batch_count = 0

            writer.writerow(row)
            batch_count += 1

        if output_csv:
            output_csv.close()

if __name__ == "__main__":
    input_file = 'sample_data.csv'  # Here enter your CSV's file name
    output_folder = 'output_batches'  # Here write the output folder
    batch_size = 50000  # Here enter the number of rows per batch

    create_batches(input_file, output_folder, batch_size)

Best practices

General advice for file imports is:

• Test with a small file before importing large datasets
• Ensure your data complies with GDPR and consent requirements
• Do not mix different contact types in the same file
• Make sure you have a unique identifier in the file
• Use consistent formatting across all imports