---
title: Format a CSV File for Import
url: https://docs.maxio.com/configuration/importing/format-a-csv-file-for-import
applies_to: Maxio Core
updated: 2026-10-12
---
# Format a CSV File for Import
The importing functionality makes data changes based on the CSV file you provide. Therefore, the files must be formatted correctly in order for the import to complete successfully. Take care when editing the file as mistakes can have unintended consequences.
## Preparing the CSV file
The spreadsheet you create contains the data used to augment the affected objects and corresponding fields during the import. Each row in the CSV represents an object and each column represents a field. For example, if you are performing a customer import, then each row of the CSV represents an individual customer and the columns represent the customers' fields.
### Field types
The system supports five types of importable field data.
| Field | Description |
| :--- | :--- |
| Alphanumeric | A mix of text and/or numbers |
| Number | Plain numbers, with a decimal point if needed, such as 12345 or 12345.00. See [How numbers are read](https://docs.maxio.com/configuration/importing/format-a-csv-file-for-import#how-numbers-are-read) for decimal places, commas, and what the import rejects. |
| Date | All date fields must use the same format, and must match the Date Format selected on the import. See [How dates are read](https://docs.maxio.com/configuration/importing/format-a-csv-file-for-import#how-dates-are-read) for the supported formats and what happens when a date does not match. |
| Email | A field that accepts one or more email addresses, such as a Customer's Email, CC Email, or Escalation Email. Separate multiple addresses with commas or semicolons; either delimiter is accepted and semicolons are automatically converted to commas on import. Any other delimiter, for example a pipe, is not recognized, and the row is rejected as invalid. A semicolon inside a quoted local part, such as `"a;b"@example.com`, is preserved rather than treated as a delimiter. |
| Binary | Binary fields can be imported or defined in the map itself. A CSV file accepts True or Yes for a true value, and False or No for a false value. Capitalization does not matter. The import map presents the same values as Yes and No when you select to input a value directly. |
### How numbers are read
Number fields accept plain numbers, with a decimal point if needed, such as **12345** or **12345.00**. A column can mix whole numbers and numbers with decimals. Number fields accept up to two decimal places, except FX Rate, which accepts up to six.
Do not include currency symbols, or a period as a thousands separator. A value such as **$5,000.00** or **€5.000.00** fails that row with the error "Please use a valid decimal amount."
Fields that offer a **Calculate Value** option, such as **MRR** and **ARR**, also accept commas as thousands separators and parentheses for a negative number. For example, **1,000.00** is read as 1000.00 and **(1000)** is read as -1000. Other number fields do not accept commas, so leave them out.
### How dates are read
Every date column in the file is read with the **Date Format** selected on the import. Choose one of these formats:
- **yyyy-mm-dd**
- **mm-dd-yy**
- **mm-dd-yyyy**
- **mm/dd/yy**
- **mm/dd/yyyy**
- **dd/mm/yy**
- **dd/mm/yyyy**
A new Map defaults its Date Format to your account's Date Display Format (**Admin** > **Account Settings** > **Locale**, see Configure Account Settings), falling back to yyyy-mm-dd. A saved Map keeps whichever format it was created with.
Check the Date Format before you import. If every day in a month-first file is 12 or lower, selecting a day-first format imports the dates with the day and month swapped.
**yyyy-mm-dd (ISO 8601) is always accepted**, regardless of which Date Format is selected. It can also carry a time, such as `2026-01-15T10:30:00` or `2026-01-15 00:00:00`. Maxio keeps only the date and ignores the time and any offset.
A value that matches neither the selected format nor yyyy-mm-dd fails that row with an error naming the expected format and an example, such as:
`Invalid date "13/01/2026": expected mm/dd/yyyy (e.g. 01/15/2026) or yyyy-mm-dd. Change "Date Format" in the import options to match your file.`
When using Excel to format dates, the underlying stored data format may differ from what Excel displays to you. If you experience import issues due to dates, open your file in a text editor and review the date records. Be sure to inspect for inconsistencies in date formats between individual rows.
### Required fields
You must have valid data in the CSV for any Maxio required fields when performing an import. On an Update import, you can omit a required custom field from the CSV, and the record keeps whatever value it already has. Create and Create and/or Update imports still require it. Rather than building the header row manually, export the object's existing records and use that file as your template, which guarantees the column names match what the importer expects.
**To generate a CSV template in Maxio**
1. Navigate to the page of the object you are importing. For example, open the **Customers** page if you are importing customers.
2. Hover over the **Download** button and select either **Export Displayed Columns - Download** or **Export All Columns - Download**. The menu also offers Google Sheets versions of both, which save to a Google Sheet instead of downloading a file.
3. The CSV file then downloads to your computer. Open the file to view the spreadsheet and use it as the basis for a new import file.
### Convert to CSV UTF-8
The import requires CSV files saved with UTF-8 encoding. A byte order mark is fine, since the importer strips it when it reads the file. Generating the file correctly requires different steps depending on which spreadsheet software you are using to prepare the data, and on which operating system.
- **Excel for Windows**: When saving, select **CSV** as the file type. Then, click the **Tools** button in the bottom right and select **Web Options**. Open the **Encoding** tab and then select the **UTF-8** option.
- **Excel for Mac**: Select the **Windows Comma Separated Values** format when saving the file.
- **Numbers for Mac**: Click **File > Export To** and then select the **CSV** option. Expand **Advanced Options** to confirm the **Unicode (UTF-8)** option is selected.
## CSV file clean-up
Once the file is in the correct format, it likely requires clean-up to correct any remaining errors. The majority of import issues that users experience have to do with improperly formatted CSV files. Excel rarely produces a completely correct UTF-8 file, because of the various versions of the software running on equally varying versions of Windows and Mac. To avoid errors, perform some final clean-up in the file to guarantee it is ready for importing.
You should avoid editing the CSV file further in Excel once you have converted it, so you must perform this clean-up step using a text editor. We recommend Notepad++ on Windows and BBEdit on macOS. You can then check for the following common issues:
- **Bad Characters**: Many text editors contain functionality for removing bad characters. This is important as bad characters may not display in Excel. In the example below, the first row of the import contains a bad character in the Number column. You can see it in the text editor, but not in Excel.
- **Extra Rows**: A text editor should also allow you to identify extra rows and columns more easily as they display as extra commas.
- **Trailing Spaces**: Be aware of trailing spaces as they can create duplicate records.
- **Column Headers**: Each column header must have a unique name. Blank or null headers are also not permitted.
- **Leftover Errors Column**: If you're reusing a CSV that was previously exported as a failed import's results, remove any column named **Errors** before uploading. Maxio carries that column's values through unchanged into the new run, and old failure text sitting next to the new run's own status can look like the current import failed even when it succeeded. See Run an Import for the warning Maxio shows if it detects this column.
Once the file is ready, you can proceed with executing the import in Maxio.