Purpose: Use this workflow to prepare CSV files for successful import into Administrate.
This article explains formatting requirements, required fields, and common preparation issues that can prevent imports from succeeding.
Related workflows:
Related: Importing data into Administrate
Before you start
- Decide whether you are creating new records or updating existing records.
- If you are updating, confirm which fields uniquely identify records (to avoid duplicates). See:
CSV structure requirements
- One header row: Use clear, stable column names. Keep header names consistent over time.
- One record per row: Each row represents one entity (or one unit of import behavior) according to the import type you chose.
- Consistent columns: Every row should have the same number of columns as the header.
- No merged cells: CSVs do not support merged cells—avoid exporting from spreadsheets with formatting tricks.
Data formatting (common expectations)
- Dates: Use a single date format consistently across the file. Avoid mixed date formats in one column.
- Numbers: Avoid currency symbols and commas unless explicitly required. Keep numeric fields numeric.
- Booleans: Use consistent values (e.g., TRUE/FALSE or Yes/No) across the entire column.
- Whitespace: Trim leading/trailing spaces (spaces can break matching and lookups).
- Blank values: If a value is unknown, leave the cell blank rather than using placeholders like “N/A” unless the field explicitly expects text.
Lookups and references (avoid “not found” errors)
If your import uses lookup/reference fields (values that must match existing records), ensure:
- The referenced values already exist in Administrate.
- The values match exactly (including spacing/case when applicable).
- You are using the correct identifier for the lookup (name vs code vs ID—whatever the rule is for that field).
If you’re unsure which fields are used for identity and lookup, review:
Pre-flight checklist (do this every time)
- Confirm you’re using the correct import type for the object you intend to create/update.
- Confirm required columns exist and are populated (for the rows where required).
- Confirm identifier columns are present (especially for updates).
- Spot-check 5–10 rows for formatting consistency (dates, numbers, blanks).
- Remove empty trailing rows and “notes” rows from exports.
Next step
Once your CSV is clean, map your fields: