Skip to content
Legend Docs

Importing Entities from CSV

Starter CSV import requires the Starter tier or above.

CSV import lets you bulk-create landmarks, people, and teams from a spreadsheet. Instead of creating entities one at a time through the wizard, you prepare a CSV file and Legend validates it, shows you a preview, and imports the valid rows.

Accessing the Import Dialog

Section titled “Accessing the Import Dialog”

The import dialog is opened from the dashboard:

  1. Click the Add button in the top navigation bar
  2. Select Import from CSV from the dropdown

If your license tier does not include CSV import, the dialog shows a message explaining that CSV import is available on the Starter tier and above, with a link to upgrade your license.

File Format Expectations

Section titled “File Format Expectations”
  • Format: A plain CSV file with a header row
  • Encoding: UTF-8
  • Extension: .csv (the file picker accepts .csv and text/csv)
  • Delimiters: Commas separate columns; pipe characters (|) separate items within multi-value columns

A Download Template button in the import dialog downloads a sample CSV with the expected columns and example rows. Starting from the template is the fastest way to prepare a valid file.

Column Mapping

Section titled “Column Mapping”

The following columns are supported:

Column Used by Description
kind all Entity type: landmark, person, or team
name all Display name (required)
slug all Unique identifier for the entity
description all Brief summary of the entity
tags all Pipe-separated tags
categories all Pipe-separated categories
links all Pipe-separated links in Title:URL format
active all true or false
email person Contact email address
title person Job title or role
teams person Pipe-separated team slugs the person belongs to
owner landmark Team or person slug that owns the landmark
category landmark The landmark’s category
parent team Parent team slug for hierarchical teams
dependsOn landmark Pipe-separated slugs of landmarks this entity depends on
relatesTo landmark Pipe-separated slugs of related landmarks

Not every column applies to every entity type. For example, email and title apply to person entities, owner and category apply to landmarks, and parent applies to teams. Leave columns blank when they do not apply to a row.

Import Workflow

Section titled “Import Workflow”
  1. Open the import dialog: Dashboard > Add > Import from CSV
  2. Download the template (optional): Use the Download Template button to get a sample file
  3. Select your CSV file: Click Select CSV File and choose your file
  4. Review the preview: Legend parses the file and shows a summary with the total rows, valid rows, and rows with errors
  5. Review row details: The preview table lists each row with its status, kind, and name, plus any validation errors
  6. Import: Click Import N Entities to create the valid entities. The button is disabled if the file cannot be committed
  7. Confirm: A success message confirms how many entities were imported

The preview runs in preview mode and makes no changes. Nothing is created until you confirm the import.

Tier Limits and Cap-Aware Behavior

Section titled “Tier Limits and Cap-Aware Behavior”

CSV import is cap-aware: imported entities count against your license tier’s limits, and Legend refuses to import more than your tier allows.

During preview, Legend checks each row against your tier’s entity limits. If importing would exceed a limit, the preview shows a Tier Limit Exceeded panel listing each violation in the format:

landmarks: importing 60 would exceed limit of 50 (currently 10)

When any tier violation is present, the import button is disabled and no rows are committed. To import, either:

  • Reduce the number of rows in your CSV so the import fits within your tier’s limits, or
  • Upgrade your license tier for higher limits

See Plans and Pricing for the entity limits per tier, and License Management for how tier limits are enforced.

Handling Validation Errors

Section titled “Handling Validation Errors”

Rows with invalid data are flagged in the preview with an error status and a message describing the problem. Common issues include:

  • Missing or duplicate name or slug values
  • An unknown kind value
  • Referenced teams or owners that do not exist
  • Malformed links (missing the Title:URL separator)

Fix the flagged rows in your CSV and re-upload the file. Invalid rows are not imported even if valid rows in the same file are committed.

Section titled “Related”