Skip to main content

Import Data (CSV): System Behavior, Templates, and Field Types

Updated

This article explains how the Import Data feature works in Administrate, including how CSV templates are structured, how data is processed, and how fields and lookups behave during import.

Contents

Overview

The Import Data feature allows you to create and update records in bulk using CSV files. It supports Accounts, Contacts, Events, Course Templates, Resources, and other entities across the platform.

Imports use the same structure as the GraphQL API, meaning:

  • available fields reflect the current system configuration
  • custom fields are supported automatically
  • new functionality becomes available without template changes

How imports work

Each import follows a consistent process:

  1. select an entity (for example, Event or Contact)
  2. select an action (for example, create or update)
  3. download a system-generated CSV template
  4. populate the template with your data
  5. upload the file and run the import

Imports perform upsert operations, meaning they can create or update records depending on identifiers and matching logic.

Import processing and statuses

Imports are processed asynchronously in scheduled batches.

You may see the following statuses:

  • Pending: queued for processing
  • In Progress: currently being processed
  • Completed: all rows processed successfully
  • Partial: some rows succeeded, others failed
  • Failed: no rows processed successfully

Large imports are processed in batches. For example, files with 10,000+ rows may be split into multiple processing cycles.

Understanding CSV templates

Every import template includes four required header rows. These rows define how the system maps your data and must not be modified or removed.

Row 1 Field name Example: Email Address
Row 2 GraphQL field reference Example: input/emailAddress
Row 3 Field description Describes expected data
Row 4 Field type and requirements Example: Text (Optional)
Row 5+ Your data Begin entering values here

You must:

  • start entering data from row 5
  • keep the file in CSV format
  • follow formatting rules shown in the template

Field types and formats

Field type Behavior
ID Requires a Base64-encoded ID value
Text Accepts free text
Text (Optional) May be left blank
Fixed Must match one of the allowed values
Lookup Finds existing records by name or ID
LocalDateTime ISO 8601 format (e.g. 2025-11-04T14:00:00)
TimeZoned DateTime Includes timezone offset (e.g. 2025-11-04T14:00:00+03:00)
TimeZone Name Uses standard TZ identifiers (e.g. America/New_York)

Lookup behavior

Lookup fields connect records across entities.

When using a lookup:

  • the system first attempts to match by name
  • if no match is found, it attempts to match by encoded ID
  • if no match is found, the row fails

Lookup format:

lookup(entity, field)

Examples:

  • lookup(contacts, name)
  • lookup(locations, name)
  • lookup(currencies, code)

Common entity behavior

Some entities require specific formats or field combinations:

  • Events: require correct date/time formatting and timezone handling
  • Locations and Tax Types: use lookup fields to match existing records
  • Optional fields: may be left blank, but some fields require paired values (for example, ID vs Name)

Different actions (such as create, update, addStaff, or addPrices) may require different fields.

Handling failures and partial imports

When an import fails or completes partially:

  • download the failure file from the import record
  • review the error message for each failed row
  • correct only the failed rows
  • re-import the corrected subset

Common error causes include:

  • invalid or missing IDs
  • incorrect field formats
  • lookup values that do not match existing records

Permissions

Users must have the Import Data - Edit permission to access the import feature.

Users can only create or update records for entities they have permission to access.

Related articles