Purpose: This article helps you choose the right import action, create, update, or upsert, and shows the safe pattern for bulk updates.
Related: Importing data into Administrate
The three actions
- Create makes new records. Use it when the records do not exist yet. The risk to manage is duplicates: if some records already exist, a create import makes second copies that look valid. When in doubt, check first or use an upsert.
- Update changes existing records. Every row must identify its record (see the identifier table below). Updates are safe to run sparsely: blank cells never change existing data, so your file only needs the identifier column plus the fields you are changing.
- Upsert by external ID creates the record if Administrate has not seen its external ID before, and updates it if it has. Use it when another system (an HR platform or CRM) owns the data and you import from it repeatedly. Available for contacts, accounts, course templates, events, and learners.
How each record type is identified in updates
| Record type | Identifier column accepts |
|---|---|
| Contact | Administrate contact ID, or the contact's email address |
| Account | Administrate account ID |
| Event | Administrate event ID |
| Course Template | Administrate course template ID |
| Learner | Administrate learner ID, or the learner's contact email address |
| Registration | Administrate registration ID |
Where an email address is accepted, it must match exactly one record; a row fails if the email matches several contacts or none. Where lookups accept names or codes (for example, course templates by course code), the same one-match rule applies.
The bulk update pattern
The safest way to run a bulk update:
- Export a report containing the records you want to change, including their Administrate IDs. Reports are one of the accepted import file formats, so the export doubles as your import file.
- Edit only the columns you are changing. Delete the columns you do not intend to touch, or leave their cells blank; blank cells leave existing values alone.
- Pilot with a few rows, verify the changed records in the application, then import the rest.
- Verify with the success and failure files, and spot-check.
Three behaviors to keep in mind when updating:
- Blank never clears. A blank cell leaves the current value untouched; there is no import value that empties a field. Clearing a field is done on the record or through the API. See How updates treat blank cells.
- List fields replace in full. If you provide a list-style value (for example workplaces), the imported list replaces the existing one, so include every entry the record should keep.
- No rollback. Rows that succeed stay applied even if others fail, so correct and re-run only the failed subset.
Recommended workflow (safe and repeatable)
- Plan: decide create, update, or upsert, and confirm identifiers.
- Prepare: build a clean file. See Prepare your file for import.
- Pilot: run a small subset first.
- Scale: proceed in batches.
- Verify: reconcile outcomes after each batch. See Verifying imported data.