Prepare your file for import

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:
  • Imports & Data Logic: Matching, Updates, and Safe Operation
  • Identifiers, Lookups, and Matching Rules

Choosing your import file

You no longer need to use a fixed CSV template to import data into Administrate. You can choose whichever option works best for you:

• Download our Excel template: This is the recommended option. The template includes dropdowns for List and Option fields, so you can select valid values instead of guessing how they should be entered.
• Generate a report: Export your existing data as a starting point, then edit and re-upload it.
• Use your own file: If you already have your data in your own format, you can upload it as-is.

All three options are supported. However, using our Excel template gives you the added benefit of guided dropdowns for List and Option fields, which helps prevent formatting errors before you import.

File structure requirements

• One header row: Your file only needs a single header row with 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: Avoid exporting from spreadsheets with merged cells or other formatting tricks.

Data formatting (common expectations)

Import Data now automatically cleans up many common formatting issues for you. However, it's still good practice to follow these guidelines where possible:

• Dates: Most common date formats are automatically converted to work with Administrate. Using a consistent format across your file still helps avoid unexpected results.
• Numbers: Avoid currency symbols and commas unless explicitly required. Keep numeric fields numeric.
• Booleans: Common values (e.g., TRUE/FALSE, Yes/No) are automatically recognized and converted. Where possible, use the dropdown provided in our Excel template for these fields.
• 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 using our Excel template, List and Option fields will show a dropdown of valid values, so you don't need to guess the correct identifier for those fields.

If you're unsure which fields are used for identity and lookup, review:

• Identifiers, Lookups, and Matching Rules

Pre-flight checklist (do this every time)

1. Confirm you're using the correct import type for the object you intend to create/update.
2. Confirm required columns exist and are populated (for the rows where required). If a required column is missing, Import Data will automatically add it for you and mark it as required.
3. Confirm identifier columns are present (especially for updates).
4. Spot-check 5–10 rows for formatting consistency (dates, numbers, blanks).
5. Remove empty trailing rows and "notes" rows from exports.

Next step

Once your file is ready, map your fields:

• Configuring and running your import