This guide is for course providers who want to add many contacts to Cademy at once, or update the contacts they already have, from a spreadsheet. A contact is a person’s record in your Cademy account.
The Contacts Import reads a CSV or Excel file with one person in each row. Each row creates a contact, or updates the contact that already has the same email address. It does not create orders or places on courses. Cademy has separate imports for those, listed in the imports overview.
You need the System Admin or Course Owner role to run the import. Every Cademy plan includes it.
Before you start, know what the import does not do:
It cannot be undone.
An empty cell does not empty a field. It leaves the contact’s saved value as it is. The exceptions are listed under “When Update existing contacts is on” below.
It adds tags to a contact and never removes them.
It does not import files into a contact field that holds an uploaded file.
Prepare your file
Check these points before you upload.
Save the file as CSV or Excel. In an Excel file, Cademy reads the first sheet only.
If your file has letters with accents or symbols, such as é or £, save it as Excel. Depending on the program that saved it, a CSV file is read with these characters wrong, for example Zoë as Zoë.
Put the column headings in the first row and one person in each row below it.
Give each person their own email address where you have one. Cademy uses the email address, ignoring capital letters, to recognise a contact that already exists. Rows that share an email address end up as one contact.
A row with no email address cannot be matched by email. It creates a new contact every time it is imported.
Check that every email address is complete. A row whose email address is not valid is not imported.
No column is required. Add a column for each detail you want to import. The fields are listed under “Contact fields you can import” below.
Keep a copy of your original file, and try a file with a few rows first. An import cannot be undone, so a small test shows you the result before you import the full list.
Start from the example file
The upload step of the import has a View example file link. It opens the example contacts spreadsheet in Google Sheets. It has the headings First Name, Last Name, Email and Organisation, a placeholder column, an example column called Dietary Requirements, and one sample row. Make your own copy, or download it. Choose Excel for the download if your contacts have letters with accents or symbols, for the reason given in the list above. Then replace the sample row with your contacts and add a column for each further field you want to import. A column you do not map, such as the placeholder column, is ignored.
Contact fields you can import
During the import, a mapping table lists Cademy’s contact fields, and you choose which column of your file fills each one. For some fields the table also shows a second list beside the column, where you tell Cademy how your file writes the value.
These are Cademy’s built-in contact fields, in the order the mapping table lists them. None of them is required.
Address: Address Line 1, Address: Address Line 2, Address: City, Address: Country, Address: Postcode and Address: Region: the parts of the contact’s address. Use a separate column for each part you have.
Cademy ID: the identifier Cademy gave a contact that already exists. Map it only when you update contacts, as explained under “How Cademy matches and updates existing contacts” below. A file from another system has no Cademy IDs.
Created date: the date and time the contact was created. Map it to keep the original date from another system. Without it, a new contact gets the date and time of the import. In the second list beside the column, choose the format your file uses, for example D/M/YYYY HH:mm for 05/03/2024 09:00. Cademy reads the time in your account’s time zone. If Cademy cannot read a value in the chosen format, the row is imported without it. In an Excel file, format the column as Text before you type the dates: a cell that Excel stores as a date is saved as a date in 1970.
Email: the contact’s email address. Cademy saves it in lower case.
First Name and Last Name: the contact’s name.
Marketing Consent: whether the contact has given you marketing consent. Read “Marketing Consent in an import” below before you map it.
Organisation: the organisation the contact belongs to. In the second list beside the column, choose how your file identifies it: Organisation ID, Domains or Organisation Name. Organisation ID is selected to begin with, so change it when your column holds names. If Cademy finds no matching organisation, the contact is imported without an organisation from your file. The exception: when Create organisations when auto-linking is on under Settings, then Organisations, a name or domain that matches nothing creates the organisation. That switch is shown under Automatic Linking only while Automatically link contacts to organisations by domain is on. When a row ends up with no organisation and that automatic linking is on, Cademy applies it to a contact that has an email address, using the domain of that address.
Phone: the contact’s phone number.
Tags: one or more tags for the contact. In the second list beside the column, choose what separates several tags in one cell: a comma, the | character or a new line. A tag that does not exist yet is created.
Most of your custom contact fields are in the mapping table too, under their own names and in the same alphabetical order. A custom address field is listed as six parts, like the built-in address. A field that is not in the table, such as one that holds an uploaded file, cannot be imported.
For your custom fields, write values that the field can hold:
Yes or no fields: yes or no, true or false, or 1 or 0.
Fields with a set list of options: an option spelled as it is in the field. For a field that allows several options, separate them in the cell and choose the separator in the second list beside the column.
Number fields: a plain number, such as 12 or 12.5.
Date fields: one format throughout the column, chosen in the second list beside the column, for example YYYY-MM-DD for 2024-03-05. In an Excel file, format the column as Text before you type the dates: a cell that Excel stores as a date is saved as a date in 1970.
If Cademy cannot use a value in one of your custom fields, for example text in a number field, or an option that a single-choice field does not have, it leaves that value out and imports the rest of the row. The row is not reported as failed, so check a few contacts after a test import. In a field that allows several options, options that do not match are dropped. If none match, an updated contact’s saved choices are replaced by an empty selection.
How Cademy matches and updates existing contacts
A row either creates a new contact or matches one that already exists. Cademy matches a row to an existing contact by its email address, ignoring capital letters. The name and the phone number are not used. The one other identifier Cademy can use is the Cademy ID, described below.
At the last step of the import, the Update existing contacts switch decides what happens to a matched contact. It is on to begin with.
When Update existing contacts is on
A matched contact is updated from the row:
Each mapped field that has a value in the row replaces the contact’s saved value.
Tags in the row are added to the contact’s tags. No tag is removed.
An empty cell leaves the saved value as it is, except in the three cases that follow.
Addresses: if the row has a value for any part of an address, the whole saved address is replaced by the parts in the row. Include every part of the address, not only the part that changed.
Names and email address: the contact’s first name, last name and email address are saved again. Where the row has no value for one of them, Cademy uses the value from the learner account that person has with Cademy. Map First Name, Last Name and Email in every update so that the contact keeps the values in your file.
Marketing Consent: it is saved again on every update, as described under “Marketing Consent in an import” below.
A row that has a Cademy ID is matched by that ID first, and by its email address only if no contact has that ID. Use it to update contacts that have no email address. Take each contact’s ID from a contacts export, described in the next paragraph. Do not copy it from the list of imported contacts of a past import. That list shows every ID in capital letters, which is not always how the ID is saved, and Cademy matches the ID exactly, including capital and small letters. An ID that does not match exactly finds no contact. The row is then matched by its email address, and a row with no email address creates a new contact.
A contacts export from Cademy also has a Cademy ID column, and the mapping table matches that heading for you. The same export has a Marketing Consent column that holds true or false. Clear every false cell before you import an exported file, for the reason given under “Marketing Consent in an import” below. The guide to exporting data explains how to export contacts.
A row that matches no contact creates a new one.
When Update existing contacts is off
A row whose email address belongs to an existing contact does not create a second contact and does not change that contact’s details. Tags in the row are still added to it.
A Cademy ID column is ignored.
Every other row creates a new contact.
Marketing Consent in an import
Marketing Consent is saved for every contact the import creates and for every contact it updates, whether or not you map the field.
A cell with yes, true or 1 is saved as consent given.
A cell with no or false is also saved as consent given. So is 0 in a CSV file.
An empty cell, or the field left as Do not import, is saved as consent not given. On an updated contact this replaces the consent already saved.
Important: Write yes only for contacts who have given consent, and leave the cell empty for everyone else. Do not write no, false or 0. Include the column whenever you update contacts who have given consent, so that their consent is not replaced.
To record consent for every contact in the file, choose Fixed value for Marketing Consent and turn its switch on. To record no consent for every contact in the file, leave the field as Do not import.
Import contacts step by step
The import has four stages: open it, upload the file, map its columns, and choose whether existing contacts are updated.
Open the Contacts Import
Sign in to the admin dashboard.
Select Settings in the main menu.
Select Imports, under Tools.
Under Start an Import, select Contacts Import. The Import contacts window opens.
If Imports is not listed, your login has the Facilitator role. Ask a System Admin or Course Owner on your account to run the import.
A System Admin can open the same window from the Contacts page: select Contacts in the main menu, then Import. Where the page does not show an Import button, open the menu button marked with three dots among the page’s actions and select Import Contacts….
Upload your file
Drop your file onto Drop or Select a file, or choose Select file and pick the file on your computer. Upload one file.
Wait while the file uploads. The window then moves on by itself and shows Configure your import, with the mapping table.
If the window shows “There was an issue processing your file. Please try again.”, check that the file is a CSV or Excel file with headings in its first row and at least one row below them.
Map your columns to contact fields
Mapping tells Cademy which column of your file fills which contact field. The table lists one field per row under four headings: Cademy Field, Value Source, File Column and Sample Data.
For each field, Value Source offers three choices:
Do not import: the import takes no value for this field from your file.
CSV column: the field takes its value from a column of your file. Choose the column under File Column. The choice has this name for Excel files too.
Fixed value: every row gets the same value, which you enter or choose in the table. For example, choose one tag as the fixed value for Tags to give that tag to every contact in the file.
Cademy fills in the table to begin with. A field whose name matches one of your column headings, ignoring capital letters, is set to that column. Every other field is set to Do not import, so a column with a heading Cademy does not recognise is ignored until you map it.
Check these points before you continue:
Every column you want to import is chosen for the right field. Sample Data shows values from the first rows of the chosen column.
A column headed Marketing Consent is matched for you. Before you continue, check its cells against “Marketing Consent in an import” above: a cell that holds no or false is saved as consent given. A contacts export from Cademy writes true or false in this column, so clear every false cell before you import that file.
Created date, Organisation, Tags and some of your custom fields show a second list beside the column. Choose the column first, because choosing a different column sets the second list back to its first option. Then check that the second list matches your file.
At least one field is mapped. The window lets you continue with every field set to Do not import, but that import creates no contacts and stays at PROCESSING in your list of imports.
Then select Next.
Choose whether to update existing contacts
Check the number of records Cademy will try to import. It is the number of rows below your headings.
Leave Update existing contacts on to update the contacts that match a row, or turn it off to keep the details of matched contacts as they are. While it is on, a box titled Deduplication Logic states that contacts are matched by the email column.
Select Import Data. The window closes and a message confirms that the import is being processed. To change the mapping first, select Back. The mapping table then starts again from Cademy’s automatic matches, so make every choice again, including the second lists and fixed values, before you select Next.
Check the result
Cademy processes the file after you select Import Data. The window says to allow a few minutes. You can keep working in Cademy while it does.
When processing finishes, Cademy emails the result to the user who started the import, if that user still has access to the account. The email gives the number of contacts imported and lists each row that failed, with its error.
To review an import in Cademy, open Settings, then Imports, and find it in the Your Imports table. The newest import is at the top, and the table refreshes while an import is processing.
TYPE: Contacts.
IMPORTED: the number of rows that did not fail. It includes rows that updated a contact, and rows that matched a contact and left it unchanged because the switch was off. Select the number to list the contacts with their names, email addresses and IDs. The list shows the IDs in capital letters. The eye button beside a contact opens it in a new tab, which needs the System Admin role.
FAILED: the number of rows that were not imported. When the number is a link, select it to see each failed row’s ROW NUMBER and REASON. A number that cannot be selected means that no reasons were stored for that import. Row 1 is the first record below your headings, which is row 2 of a spreadsheet with no empty rows.
STATUS: PROCESSING while Cademy works through the file, then PROCESSED when it has finished. PROCESSED does not mean that every row succeeded, so always check the FAILED column. The FAILED status is not used for a Contacts import.
A row fails when its email address is not valid, or when Cademy meets an error while saving it. Each row is imported on its own, so one failed row does not stop the others.
To fix failed rows, correct them in your spreadsheet and import a file that contains only those rows.
If an import stays at PROCESSING and no email arrives, look for its contacts in Cademy before you upload the file again, so that you do not import them twice. Then contact Cademy Support with the import’s type and the date and time shown in Your Imports.
Related guides
The imports overview: where imports are, which imports Cademy has and how to review past imports.
Manage Contacts: find, edit, merge and delete contacts after an import.
Frequently asked questions
How does Cademy decide that a contact already exists?
By the email address, ignoring capital letters. While Update existing contacts is on, a row that has a Cademy ID is matched by that ID first. No other field is used.
What happens to a row with no email address?
It creates a new contact, and it does so again each time the same row is imported. The exception is a row with a Cademy ID while Update existing contacts is on, which updates the contact that has that ID.
Will importing the same file twice create duplicate contacts?
Not for rows that have an email address. The second import matches the contacts that the first one created. Rows without an email address are created again.
Can the import remove information from a contact?
An empty cell leaves the saved value as it is, and no tag is removed. On an updated contact, three details can still change when your file gives no value for them: Marketing Consent, the parts of an address that are missing from a row which has other parts, and the name or email address. They are explained under “When Update existing contacts is on”. A field that allows several options is also emptied on an updated contact when the cell holds only options the field does not have.
Can I undo an import?
No. Cademy has no undo for imports. Select the IMPORTED number in Your Imports to list the contacts the import created or matched, then correct them in Cademy.
Which file types can I import?
CSV and Excel files. In an Excel file only the first sheet is read, and the first row must contain the column headings. If your file has letters with accents or symbols, save it as Excel, as explained under “Prepare your file”.
Where do I see the rows that failed?
Open Settings, then Imports, and look under FAILED for the import. When the number is a link, select it to list the failed rows. The email sent when the import finishes lists them too.