You can import Customers into Spektrix using the Importer. This can be useful if you collect customer data outside of Spektrix in person, through a wifi system, or if you receive shared data which has been collected elsewhere.
By using the Importer, you can create multiple Customers in bulk without having to individually create and populate each Customer Record. You can also use a Customer Import to bulk apply Tags to existing Customers.
The concepts in this article require a basic understanding of Imports and Customers.
Before reading this article, make sure you’re familiar with:
TIP: To start importing Customers, you'll need to request access to the Importer tool. To learn more about getting started with imports, read Introduction to doing your own imports.
How does importing Customers work?
You can import Customers into Spektrix using a Customer import type. This type of import can create new Customer Records or update existing Customers that are already in your system.
You can add or update the following information about a customer:
- Name
- Address
- Phone Number
- Birth Date
- Tags
- Attributes
- Contact Preferences
- Notes
To import Customers into Spektrix, you’ll first need to compile the data about each customer into a CSV file. You’ll then upload the CSV using the Importer to add the data to your system.
The CSV file you upload must be formatted exactly in line with the guidance in this article.
Before uploading your import, you’ll need to thoroughly check your data. If your data does not match the required format, this can result in incorrect data being uploaded into your system.
WARNING: You’re responsible for the data you import and for fixing any mistakes. Spektrix can’t reverse the imports you upload.
Successfully imported data will be available alongside your other data in the Sales and Opportunities Interfaces, and in Reports and Customer Lists.
After uploading your import, you should spot-check your uploaded data to ensure that it has been imported as you expected.
Matching to existing customers
You can import data into new or existing Customer Records.
When importing, there are two properties that the importer can use to find a “match” with an existing customer:
- Customer ID (SpektrixId)
- Email address (EmailAddress)
By default, the importer will always scan for a matching Customer ID first. If a Customer ID in your import file matches an existing Customer ID in your system, then the data will be imported against your existing customer.
If you also choose to match on Email Address, after checking for Customers with a matching Customer ID, the importer will check for matching email addresses. If a Customer’s email address in your import file matches an existing Customer’s email address in your system, then the data will be imported against your existing Customer. If there's no matching Customer ID or email address, then a new Customer Record is created.
if you don't choose to match on Email Address, then only Customers with matching Customer IDs will be considered a match. If there is no matching Customer ID, then a new Customer Record is created.
Each Customer Record in Spektrix must have a unique email address. This is designed to prevent duplicate Customer Records in your system.
An email address can’t be accepted by the importer if:
- The email address is already used by another record. If an imported email address is already on the system but you have not chosen to match on email address, then a new customer will be created, but the email address will be stored in a new Customer Attribute named “Duplicate Email”.
- The email address is invalid. In this case, the invalid email address will be stored in a new Attribute named “Invalid Email”.
TIP: If you’re importing email addresses, check the match on email address box to avoid adding duplicate customers into your system.
Organisations
Organisations can only be matched on Customer ID. This means that importing Organisation records without a Customer ID will create duplicates.
Import Modes
For Customer Imports, there are two different ways you can add information to your system.
The two modes are:
Generally, Overwrite mode changes existing data in the system, whereas append adds data where it doesn't currently exist.
Overwrite and Append modes work differently depending on the type of data you are importing. In this section, we’ll give a general overview of how the two modes work. You should refer to each section for details about how the modes work for each specific type of data.
Overwrite
The Overwrite mode replaces existing data with new data or creates a new record.
To overwrite data on an existing Customer Record:
- The import must find a Customer Record which matches (for example, on the Customer ID or email address)
- It does not matter whether the field that you wish to overwrite already has a value or not.
Append
The Append mode adds new data to fields which have not been set. Append mode will not change the data in fields that are already populated.
To append data to a Customer Record:
- The import must find a Customer Record which matches (for example, on the Customer ID or email address)
- There must be no data in the field that you want to update
Considerations for importing Customers
Your customer data is valuable and sensitive. This means that there are extra considerations to make when importing Customers.
When you use Overwrite mode, you must be confident that the data you are importing is more accurate than the data you already have in the system because you cannot recover overwritten data.
Consider the following questions before uploading an import in Overwrite mode:
- Is this data from a source you trust?
WARNING: Purchased contact lists can severely damage your sender reputation. For this reason, we do not recommend that you import purchased contact data.
- Is the data you’re importing more up to date than the data you have in the system?
- How are you going to use the data you import?
- Could you split the import into multiple parts? Instead of importing all of your data in Overwrite mode, could you import some of it in Append instead?
- Are you importing Contact Preferences? If so, have you considered what automated Mailings or Dotdigital Programs the new customers may automatically receive, for example, a Welcome Program.
How to import Customers
To import Customers into Spektrix, follow the steps below in order:
1. Prepare your CSV file
You’ll need to create a CSV file which contains the data you want to import to your system.
To do this, you’ll need to use a CSV editor program such as Excel or a third-party tool like Rons Data Edit (if approved by your IT team). Make sure that the CSV editor program you are using can save files in the UTF-8 format.
WARNING: If you use Excel to edit your CSV file, be aware that date and phone number formats won’t automatically be formatted correctly. Always double check the format of these fields when preparing an import.
If you're using a formatted report from Spektrix as the basis of your CSV file, you must still check the data and ensure it’s in the correct format for the import.
REMINDER: Your CSV File must be formatted exactly as outlined in this article to import successfully.
Your CSV file
For an import to be successful, your CSV file must meet the following standards:
- All required fields must be populated with data. Read the Required Data Fields section of this article for details about each of the required fields for a Customer import.
- Each column name must match the correct column name exactly, including capitalisation and spaces. Read the Required Data Fields section of this article for details about each of the column names.
- Data must match the required format for the field type. For example, you can’t import free text into a Yes/No field. For more information, read the Field Types section of the Introduction to the Importer.
- Each CSV must be in the UTF-8 encoding format. Read more about UTF-8 encoding in the Introduction to the Importer.
Required Data Fields
In the table below, we’ve outlined the different data fields that can be included in Customer imports and whether they are required.
If a field that isn’t required is left blank, then no data will be imported into this field.
| Column Name | Description | Required |
| SpektrixId |
If you have one, enter the Spektrix Customer ID that you’d like to update the details of. This field is not required if you’re importing new customers. Read more about matching to existing customers.
|
No |
| EmailAddress |
Enter the customer’s email address. Read more about matching to existing customers.
|
No |
| ClearEmailAddress |
This column can be used to clear an existing email address from the individual and will deactivate the individual's online account. This column can’t be used to replace the existing email address with a new email address. It cannot be set to true when an email address has been included in the same row. This will only work while in Overwrite mode.
|
No |
| Title |
Enter the customer’s title. You can enter {clear} in this column to remove an existing Title value.
|
No |
| FirstName |
Enter the customer’s first name. If you include the customer’s first name you must also include the last name.
|
Yes, if creating a new Customer or if the other individual name fields are included |
| LastName |
Enter the customer’s last name. If you include the customer’s last name you must also include the first name.
|
Yes, if creating a new Customer or if the other individual name fields are included |
| OrganisationName |
Enter the name of the organisation.
|
Yes if setting up a new Organisation record |
| Address1 |
Enter the first line of the customer’s address. If Address1 is included, you must also include PostTown, Postcode and Country.
|
Yes, if other individual address fields are included |
| Address2 |
Enter the second line of the customer’s address.
|
No |
| Address3 |
Enter the third line of the customer’s address.
|
No |
|
Address4
|
Enter the fourth line of the customer’s address.
|
No |
| Address5 |
Enter the fifth line of the customer’s address.
|
No |
| PostTown |
Enter the customer’s town. If PostTown is included, you must also include Address1, Postcode and Country.
|
Yes, if other individual address fields are included |
| Postcode |
Enter the customer’s post code / Eircode / zip code / postal code. In the UK this is their post code. If Postcode is included, you must also include Address1, PostTown and Country.
|
Yes, if other individual address fields are included |
| AdministrativeDivision |
Enter the customer’s administrative division. In the UK this is their County.
|
No |
| Country |
Must have a case-insensitive match with the system’s list of countries. If the Country string cannot be matched, then the importer will use the country the system has been set up under (e.g. a UK system will default to ‘Country’ to UK). If Country is included, you must also include Address1, PostTown and Postcode.
|
Yes, if other address fields are included |
| IsDefault |
Enter Y in this column if you’d like to set this as the customer’s default billing and delivery address. If you enter N or leave the column blank then the customer’s default address will not be updated. If it’s a new customer then their first address will always be default. Overwrite Mode Only: This changes the Default Billing and Default Delivery address to the imported address.
|
No |
| Phone |
Enter the customer’s phone number. You can enter {clear} in this column to remove an existing Phone value.
|
No |
| Mobile |
Enter the customer’s mobile phone number. You can enter {clear} in this column to remove an existing Mobile value.
|
No |
| DateOfBirth |
Enter the customer’s date of birth. The date must be in the format yyyy-mm-dd.
|
No |
| ClearDateOfBirth |
Enter Y in this column to clear the customer’s date of birth (must be in Overwrite mode). Enter N or leave this column blank to retain the Customer’s existing Date of Birth. This column cannot be set to Y if DateOfBirth has been included in the same row.
|
No |
| Notes |
Enter a note about this customer. In Append mode, this will be appended to any existing content in the notes field, with two line breaks in between. In Overwrite mode it will replace any existing content.
|
No |
| FundraisingNotes |
Enter a Fundraising note about this customer. In Append mode, this will be appended to any existing content in the notes field, with two line breaks in between. In Overwrite mode it will replace any existing content.
|
No |
|
Tag:{TagGroup}:{TagName}
|
Amend this column header to import any custom Tags you want to apply. Enter Y in the column to indicate that the customer has the Tag. If there is not an existing Tag of the same name then a new Tag will be created. Read more about importing Tags in the Tag Group section of this article.
|
No |
|
ContactPreference:{ContactPreferenceName}
|
Amend this column header to import any Contact Preferences you have on your system. You can set Contact Preferences as:
If there is not an existing Contact Preference of the same name then a new Contact Preference will be created. Read more about importing Contact Preferences in the Contact Preferences section of this article.
|
No |
|
CustomField:{CustomFieldName}
|
Amend this column header to import any custom Attributes you have on your system. Read more about importing Custom Fields in the Customer Attributes section of this article. If there is not an existing Attribute of the same name, then a new Attribute will be created.
|
No, unless set as required |
|
PartnerCompanyContactPreference:{PartnerCompanyName}
|
Amend this column header to import any Partner Company Contact Preferences you have on your system. You can set Contact Preferences as
If there is not an existing Contact Preference of the same name then a new Contact Preference will be created. Read more about importing Contact Preferences in the Partner Company Contact Preferences section of this article.
|
No |
|
IsActive
|
Enter Y to mark the customer as active. Enter N or leave the column blank to import the customer as inactive. In append mode, this column will only make new customers active or inactive - it will not affect existing customers. In overwrite mode, this will change the status of existing customers.
|
No |
Clear
For some data fields, you can use an overwrite import to remove any existing data.
This works in two different ways depending on which types of data you’d like to clear.
For email addresses and date of birth values you can enter Y in the ClearEmailAddress or ClearDateOfBirth column.
For the following data fields, you can enter {clear} in the column value to remove the data:
- Phone
- Mobile
- Title
- Attributes that are Dropdown, Date, Text or Currency type
For example:
| SpektrixId | Mobile |
| I-MN00-JMER | {clear} |
Addresses
When you import a customer’s address, you can update:
- The address
- The default address (both the default billing and delivery address)
Importing addresses is based on three factors:
- Whether there is a match with an existing customer
- If you are using Overwrite or Append Mode
- If there is a match with an existing address
For an address to match, the import file must have the same value in Address1 field and the Postcode field as the existing customer record. Matches will only consider letters and numbers, any spaces in post codes or other characters will be ignored.
For example, the following two addresses would be considered a match:
| Address 1 | Address 2 | Address 3 | PostTown | Postcode |
| 2200 | Farimount Avenue | PA | Philadelphia | 19130 |
| 2200 | 19130 |
In Append mode:
- When a Customer match is found but there is no address match, then the new address will be added. The new address will only be set as the default address if there is no other address on the Customer Record.
- When a Customer match is found and there is an address match, the existing address on the Customer Record will not change.
In Overwrite mode:
- When a Customer match is found but there is no address match, then a new address will be added. The new address will become the default if there is no other address on the Customer Record or if you combine it with a Y in the IsDefault column.
- When a Customer match is found and there is an address match, then the existing address will be overwritten with the new address from the import file. The new address will become the default if there is no other address on the Customer Record or if you combine it with a Y in the IsDefault column.
If there’s no customer match in either mode, a new address will be created and set as default.
REMINDER: You can’t use an import to remove a customer’s address. It is only possible to update the capitalisation and spacing of Address line 1 and the Post / Zip code. Other address fields can be updated.
Tags
You’ll need to create a column for each Tag that you want to import against your Customers.
The column name for a Custom Field for Tags is made up of two parts:
Tag:{TagGroup}:{TagName}
- Replace {TagGroup} with the name of the Tag Group that the Tag you are importing belongs to. For example, Customer Type or Fundraising.
- Replace {TagName} with the name of the Tag you are importing. For example, Employee or Regular Giver.
For example, the column name for importing an “Employee” Tag from the “Customer Type” Tag Group would be:
| Tag:CustomerType:Employee |
TIP: Don’t forget to include the colon. The completed column name should not contain any curly brackets.
In your Spektrix system, you’ll find your Tag Group and Tag names in the Admin Interface > Customers > Tags > select the Tag group:
REMINDER: If there is not an existing Tag or Tag Group of the same name then a new one will be created.
Overwrite and Append
Tags are a Yes/No type. If a Customer does not have a Tag, it is considered not set. In both Append and Overwrite modes, you can set the Tag from a not set state.
- In Append mode:
If a Customer does not already have the Tag, you can apply the Tag.
- In Overwrite mode:
If a Customer does not already have the Tag, you can apply the Tag and if the customer already has the Tag, it can be removed.
Contact Preferences
You’ll need to create a column for each Contact Preference that you want to import against your Customers.
To format the column name of your Contact Preference, use the following formula.
ContactPreference:{ContactPreferenceName}
Replace {ContactPreferenceName} with the name of your Contact Preference. For example, the column name for importing a Contact Preference named “Agreed to Email” would be:
| ContactPreference:Agreed to Email |
TIP: Don’t forget to include the colon. The completed column name should not contain any curly brackets
In your Spektrix system, you’ll find your Contact Preference names in the Settings Interface > Customers > Contact Preferences:
REMINDER: If there is not an existing Contact Preference of the same name then a new Contact Preference will be created.
Overwrite and Append
Contact Preferences can have a Yes, No or Not Asked response.
If a Customer has the Not Asked response against a Contact Preference it is considered “not set”. In both Append and Override modes, you can update the Contact Preference response from a not set state.
- In Append mode:
If the Contact Preference is Not Asked, you can update the response to Yes or No. If the Contact Preference is Yes or No already, it cannot be updated in Append mode.
- In Overwrite mode:
Regardless of the current response, the Contact Preference can be changed to Yes, No or Not Asked.
Partner Company Contact Preferences
You’ll need to create a column for each Partner Company Contact Preference that you want to import against your Customers.
To format the column name of your Partner Company Contact Preference, use the following formula.
PartnerCompanyContactPreference:{PartnerCompanyName}
- {PartnerCompanyName}
Replace {PartnerCompanyName} with the name of the Partner Company you are importing. For example, Touring Company or Partner Theatre.
Example:
In this example, the column name for importing a “Touring Company” Partner Company would be:
PartnerCompanyContactPreference:Touring Company
TIP: Don’t forget to include the colon. The completed column name should not contain any curly brackets.
In your Spektrix system, you’ll find your Partner Company Contact Preference names in the Settings Interface > Partner Companies > Partner Companies:
REMINDER: If there is not an existing Contact Preference of the same name then a new Contact Preference will be created.
Overwrite and Append
Contact Preferences can have Yes, No or Not Asked responses. If a Customer has the Not Asked Contact Preference it is considered “not set”. In both Append and Override modes you can update the Contact Preference response from a not set state.
- In Append mode:
If the Contact Preference is Not Asked, you can update the response to Yes or No.
- In Overwrite mode:
The response to the Contact Preference can be changed to Yes or No.
Customer Attributes
You’ll need to create a column for each Customer Attribute that you want to import against your Customers.
TIP: If you have a required Customer Attribute, then it must be included in the input file regardless of if you're appending, overwriting or creating new customers. In many cases, briefly making this attribute not required may be the easiest option.
To format the column name of your Customer Attribute, use the following formula:
CustomField:{CustomFieldName}
Replace {CustomFieldName} with the exact name of your Customer Attribute definition.
REMINDER: Attribute names are case sensitive and must match exactly (including spaces) to be successfully imported. You'll also need to remove the curly brackets. Do not add a space between the colon and the start of your Attribute name.
For example, if your Customer Attribute is Audience Spectrum Segment then your column header would be:
CustomField:Audience Spectrum Segment
If your custom Customer Attribute is a dropdown list, then the data in the column must match the dropdown values exactly.
For example:
| CustomField:Audience Spectrum Segment |
| Experience Seekers |
| Commuterland Culturebuffs |
WARNING: If you have Customer Attributes set up on your system which require unique values, you will need to ensure that a unique value is supplied, otherwise, the row will not be imported. Individual rows will also fail if you do not supply values for required Attributes.
In your Spektrix system, you’ll find your Customer Attribute names and values in the Settings Interface > Attribute Definitions:
REMINDER: If there is not an existing Attribute of the same name then a new Attribute will be created.
Overwrite and Append
Importing Customer Attributes in Overwrite or Append mode is different depending on the type of Attribute.
Click through the tabs below to understand how importing different types of Attributes works.
-
Dropdown, Date, Text or Currency Attributes are all considered as text when importing.
- In Append mode:
If a Customer does not have a value for an Attribute, it is considered “not set”. In both Append and Override modes, you can set the Attribute value from a “not set” state.
- In Overwrite mode:
Regardless of whether the Attribute is set, the new value from the import will replace any existing value.
-
Checkbox Attributes work in the same way as Tags - they are a Yes/No type.
- In Append mode:
If the checkbox is “not set” (unchecked) then it can be set to checked. A checkbox cannot be changed from checked to unchecked in Append mode.
- In Overwrite mode:
Regardless of whether the Attribute is set, the new value from the import will replace any existing value. In Overwrite mode you can change a checkbox from checked to unchecked or unchecked to checked.
TIP: Protected Attributes can only be viewed in Spektrix with the Can view and edit protected data user role. You can import to a protected Attribute regardless whether you have the protected data user role or not.
Example
Click the image below to see a detailed example of a Customer Import. This example has been formatted correctly with all the required headings and is ready to be uploaded.
REMINDER: Don’t forget to save your CSV in the UTF-8 encoding format.
2. Validate your data
The Importer is found in the Settings interface:
TIP: To access the Settings Interface, you’ll need the Settings Administrator Role. If you don’t have this Role, ask the Settings Administrator in your organisation to add this Role to your User Account.
Each import type has two processes that can be run against it: Validate and Import.
All imports must be validated before they are imported.
The validation process checks the data in the input file against validation rules to identify any issues in the CSV file. It does not check against data already in Spektrix (for example, customer data), so you may still get data-specific errors when running your import.
WARNING: Do not run your import until you have received a successful validation CSV.
How to use the Validator
REMINDER: CSV files must be in the UTF-8 format and contain all of the required information for your import.
Once you’ve clicked Run Validator, you’ll see a Job Submitted icon in the top left of the screen:
Hover your mouse over the green check mark and click the link to download the CSV file to see the results:
How to read the validation document
The validator will give one of two types of responses:
- No validation error found
If the validation is successful, the CSV will contain a message which reads: Validation completed successfully.
- Validation error found
If the validation is unsuccessful, the CSV will contain a message explaining the failure.
How to avoid common errors
Below are some tips that can help you avoid common errors:
- Always check your data. If possible, we recommend working with another member of your team to perform the check.
- Depending on the type of error, it may be that records without error messages also fail to import. Therefore, you should always spot check unaffected records to see if they have successfully imported.
- If you use Excel to edit your CSV files, you’ll need to set the date and phone number format every time you open the file. Even if you save the file with the correct format, the next time you open the file, you’ll need to update the date format again.
- Remember to save your file in the csv UTF-8 format.
- If you need to re-import some rows of your data because they have failed, take out the successfully imported Customers from your file.
- If you’re using Excel to create your import file, errors will refer to the number of the error. This will not correspond directly with the row number in Excel. For example, “Error processing record 24” refers to Row 25 of your Excel file.
3. Process the import
If your CSV file passes validation, then continue on to import the file.
REMINDER: A successful validation of your CSV file does not always lead to a successful import of your data.
How to run an Import
-
Select the Import Type: Customers:
-
Click Import:
-
Complete the Import CSV details:
a. Import Mode: Choose Append or Overwrite. Check the box to match on email address. Read more about matching to existing customers.
b. Foreign Id Customer Custom Field Name: Leave blank
c. Foreign Id Order Custom Field Name: Leave blank
d. Upload the CSV file: Click select file and browse to the location on your computer where the CSV file is saved
After clicking Run Importer, you’ll see a pop up asking you to confirm the number of rows in the import file:
Click Confirm to continue with the import, or click Cancel to go back.
Once you’ve clicked Confirm, you’ll see a Job Submitted icon in the top left of the screen:
Hover your mouse over the green check mark and click on the link to the CSV file to download and see the results:
You’ll also receive an email notification to let you know the import is complete. This will be sent to the email address registered to your User Account.
WARNING: Download and review the import results file before attempting to re-upload an import.
Import results file
A CSV report will be generated and available to download with the result of your import.
If the import is successful, you'll see Import completed successfully:
If the import fails, you’ll see a message with an error reason.
For example:
Error processing record 1: FirstName and LastName must be provided if any part of an Individual's name is provided.
Another example of a failed validation error message is:
VALIDATION FAILED WITH CsvDataException
Error processing row 1. Invalid date. Dates must be in the format yyyy-MM-dd. '20/03/2025' is not valid.
In this second example, the validation failed due to an incorrect date format.
The CSV report will contain a row for each record that had an error.
Each row explains:
- On what record the error occurred
- The details of the error
- The contents of the object that caused the error (in a single cell, with line breaks between properties)
This file only lists errors. Any rows not listed will have been imported successfully.
Depending on the error in the import results, you may want to amend the data and re-attempt to import for those specific rows. If you are re-attempting an import, remove any successfully imported Customers from your file.
REMINDER: Depending on the type of error, it may be that records without error messages also fail to import. Therefore, you should always spot check unaffected records to see if they have successfully imported.
4. Check your data
Once you’ve completed your import, we recommend spot-checking your imported Customers to ensure the data is being returned as you expected.
This is an example of how an Imported Customer might look in the Sales Interface:
Choose a few of the Customers you have imported and check that all of the fields you have imported are correct.
Further Reading
To continue learning about importing, take a look at the following articles: