Prepare a CSV for import: templates, columns and errors
Start from the importer's own template, keep its column names, put one record per row and save the file as UTF-8. Most failed imports come from a missing required column, a repeated ID, a badly formatted date or number, or a value the system does not recognize.
A CSV file is a plain-text table: one line per row, with a separator between the cells. It looks simple, which is exactly why it goes wrong. Spreadsheet apps quietly change codes, dates and separators when they save, and the importer on the other side reads what is really in the file, not what you saw on screen.
Start from the template
Most business software offers a template for each record type. Use it, even if you already have a spreadsheet. The template tells you the exact column names the importer expects, and copying your data into it is faster than guessing. Keep the header row as it is: renaming a column is the easiest way to make a value disappear during import.
Rules for a clean file
| Rule | Why |
|---|---|
| One record per row | No subtotals, notes or blank lines between records |
| A stable ID in every row | Lets related files and later re-imports find the right record |
| Save as UTF-8 | Keeps accented names and symbols intact |
| Dates as YYYY-MM-DD | Avoids mixing up day and month |
| Numbers without thousands separators | "1.250" can mean one and a quarter or twelve hundred and fifty |
| Codes stored as text | Spreadsheets drop leading zeros from postal codes and customer numbers |
The errors that stop most imports
- A required column is missing. Usually the ID column, or one that was renamed. Compare your header row with the template.
- The same ID appears twice. Often a duplicate customer that slipped through. Our checklist for cleaning data before an import shows how to find them.
- A value has the wrong type. Text in a number column, or a date the importer cannot read.
- A value is not recognized. A country written out in full where a two-letter code is expected, or a status that does not exist in the new system.
- The file was saved in the wrong encoding. Names come out as strange characters. Save again as UTF-8.
Separators and encodings
Despite the name, not every CSV uses commas. Many European spreadsheet apps save with semicolons, because the comma is the decimal mark there. Good importers detect this, but check the file in a plain-text editor if an import puts every value into one column.
Preparing a CSV for Swiftly Workspace
In Swiftly Workspace, an admin imports from Administration, then Data Import. Start a session, tick the record type, and click Download CSV Template. Row one of the template holds the column names; row two describes each column, so overwrite it with your data or delete it. Upload takes a CSV or an XLSX file, and a CSV may be separated by commas, semicolons or tabs, saved as UTF-8 (with or without a byte-order mark), UTF-16 or Windows-1252.
| Record type | Required columns |
|---|---|
| Customers | external_id |
| Customer addresses | customer_external_id, address_line_1, city, country |
| Customer contacts | customer_external_id, first_name, last_name |
- Missing columns stop the upload. If a required column is not in the file, the upload is refused, so check the header row before you upload. Each contact row also needs at least one of the two names.
- Customers before the rest. Addresses and contacts find their customer through
customer_external_id, so import the customers, then the addresses and contacts, each record type in its own session. - Country is a two-letter code. Use codes such as BE or DE in the
countrycolumn; an address whose country does not resolve to one is flagged. - Validate tells you what is wrong. After the upload, Validate reports problems row by row: an
external_idused twice in the file, a missing required value, a value of the wrong type, and for contacts a malformed email address or a phone number with fewer than seven digits. A filled column for a field your company has hidden is reported as information, not as an error. - Leave reference columns empty for now. A value in a column such as customer type, status or salutation becomes a lookup to match, and Commit waits for it. Set those on the records after the import.
The whole click path, from the session to Commit, is in how to import customers on Mac.
More on the bigger picture: the order to import record types in, the switching checklist for the cut-over, and exporting your data to CSV for the way back out.
Frequently asked questions
Which encoding should I save a CSV in?
UTF-8, unless the importer asks for something else. It keeps accented letters and symbols intact. If names come out as strange characters after an import, open the file in a plain-text editor, save it again as UTF-8 and upload it again.
How do I keep leading zeros in a CSV file?
Format the column as text before you paste or type the values, or the spreadsheet will treat them as numbers and drop the zeros. Check the saved file in a text editor: the zeros must be there.
Can I rename the columns in an import template?
Better not. Importers match values by column name, so a renamed column is usually refused or ignored. Keep the template's header row exactly as it is, and leave a column empty if you have no data for it.
Run your business on Apple.
Create your account on the web, then set up your workspace in the app on your iPhone, iPad or Mac.
Create your account
