---
title: Importing Photos and Documents
description: How to bring photos, documents, metadata files, and external archive records into your collection.
section: guides
order: 1
updated: 2026-07-14
verified: 2026-07-14
related: [reference/supported-file-formats, getting-started/first-import, guides/identifiers-and-numbering, guides/custom-fields, guides/working-with-artifacts]
features: [import-sessions]
---

# Importing Photos and Documents

This guide covers every way to bring material into Preservated, what each step of the import wizard decides, and how to handle problems mid-import.

If you just want to try a quick upload, start with [Run Your First Import](/docs/en-US/getting-started/first-import) instead.

## One wizard for every source

Every import follows the same steps, no matter where the records come from:

1. **Source** — choose **Upload files or folder** or **Paste source URL**. That single choice is the only thing that differs between sources; everything after it is identical.
2. **Reconcile** — only shown for a file upload that has both a metadata file and local asset files. Resolve any ambiguous filename matches, and decide what happens to files and records that didn't match each other.
3. **Map Fields** — route detected collections, choose how objects are numbered, and map each source field to an artifact field (with a transform if needed). Skipped for a media-only upload (see below).
4. **Import Options** — decide the record range, duplicate handling, asset source, and AI/enrichment.
5. **Review** — confirm the session name, source summary, and a preview of the first records.
6. **Status** — watch progress on the session page after the import starts.

The first decision is only whether you have **files to upload** or a **URL**:

- **Upload files or folder** — select files, select a folder, or drag files or entire folders onto the page. What you select is a **file package**: zero or one metadata file (CSV/TSV, JSON, JSONL/NDJSON, or XML — including PastPerfect PPWE/DPLA and OAI-PMH response files) plus any number of local asset files of any kind Preservated supports — images, video, audio, PDFs, and Office documents. A single metadata file with no other files behaves exactly as before. Uploading only asset files, with no metadata file at all, is also supported — see **Media-only uploads** below.
- **Paste source URL** — an item, search, or harvest URL a registered source understands: Library of Congress, NYPL, the Cleveland Museum of Art Open Access API, an OAI-PMH `ListRecords` endpoint, Washington State Digital Archives, and more.

When you submit the source, Preservated analyzes it and shows what it found — record count, detected format, a per-kind breakdown of any asset files, and a small preview — before anything is created or queued.

Every import — regardless of source — runs as an **import session** with per-item tracking, so a thousand-item migration behaves the same as a ten-photo test.

## Upload a file package

Select **Upload files or folder**, then either select files, select a folder, or drag files or folders onto the page. A dragged folder is read in full, including everything in its subfolders. Preservated sorts what you selected into three groups and shows you the result before anything uploads:

- **Metadata file** — if exactly one CSV/TSV, JSON, JSONL/NDJSON, or XML file is in the selection, it's chosen automatically. A plain-text `.txt` file is only treated as metadata when it actually looks like a delimited table with a header row; otherwise it's treated as a document. If more than one metadata-shaped file is found, you choose which one is the real metadata file — the others are listed as "other data files (not imported)" and are skipped.
- **Asset files** — every image, video, audio, PDF, and document file in the selection, each shown with its detected kind. Per-kind size limits apply (see [Supported File Formats](/docs/en-US/reference/supported-file-formats)); an institution admin can raise or lower these limits.
- **Rejected files** — unsupported formats, files over their kind's size limit, and system files your OS adds automatically (`.DS_Store`, `Thumbs.db`, `desktop.ini`, and similar) are listed and never uploaded.

A package tops out at 2,000 files and 5 GB total. A selection over either limit is blocked before anything uploads, with a message telling you which limit to reduce.

### How files are matched to records

When your package has both a metadata file and asset files, Preservated matches each asset file to the metadata record it belongs to by filename — never by title, since titles are too free-form to match reliably. It checks, in order: fields your source explicitly marks as filenames (`filename`, `file`, `image`, and similar), the filename portion of any image or capture URL in the record, and identifier fields. A record can match more than one file — for example a photo and its caption sidecar — and Preservated picks the most useful one as the primary asset automatically (images first, then video, audio, and documents, then alphabetically among files of the same kind), with the rest attached as supplemental. If a filename matches two or more records, none of them is guessed at: the ambiguous files wait for you to resolve them.

### Reconcile files and records

The **Reconcile** step appears whenever your package has both a metadata file and asset files to match. It shows:

- **Ambiguous filenames**, if any — pick which record each one belongs to, or leave it unmatched.
- **Unmatched media** — asset files that didn't match any record. **Keep as standalone media artifacts** is on by default, turning each one into its own artifact; switch it off to leave them out of the import entirely.
- **Unmatched records** — metadata records with no matching file. **Keep** is on by default (a record with an image URL still downloads remotely; one without becomes a metadata-only artifact); switch it off to skip these records. This is the one-click way to import "100 records but only 5 photos" as exactly 5 artifacts — uncheck **Keep** on unmatched records and the other 95 are left out.
- **Matched records** — a recap of every match, each with a **Change primary / attach files** control if you want to override which file is primary or attach a different file.

Anything you choose to leave out here is skipped before Preservated even checks for duplicates or counts against your quota — an ignored file or record never becomes an import item.

### Media-only uploads

If your selection has no metadata file at all — just images, video, audio, PDFs, or documents — the wizard skips field mapping and the Reconcile step entirely. On **Map Fields**, you still route collections and choose how objects are numbered; every file becomes its own artifact, titled from its filename, typed from its kind (a PDF becomes a document, an audio file becomes audio, and so on).

## Recognized package formats

A few source formats are common enough that Preservated recognizes the folder shape itself and skips straight to a tailored wizard flow — no need to pick out the metadata file or match images by hand. Drag the folder onto **Upload files or folder** like any other package; if Preservated recognizes it, the Source step shows a badge naming the format instead of the generic file breakdown.

### Import a PastPerfect export folder

If your museum runs PastPerfect 5, drag the **whole install folder**, or just its `output/` export folder together with the `Images` and `Multimedia` folders, onto the Source step. Preservated recognizes the export by its file layout (a `records/` directory holding the assembled `catalog_items.jsonl` and related files) and shows a **"PastPerfect 5 JSONL export"** badge with per-type record counts.

What happens automatically:

- **Only media your catalog records actually reference gets uploaded.** Everything else in a PastPerfect install — raw per-table dumps, HTML viewers, install executables, correspondence templates — is excluded and summarized on the Source step, never uploaded. If an image or attachment a record points to is missing from what you dragged, it's listed as a warning with a downloadable list, and that record still imports without it.
- **People, creators, and sites import as person records.** Each gets a biography article built from the longer PastPerfect notes (occupation, residence, family, publications, and similar). A person PastPerfect marks as living — or who has a birth date but no death date — stays **staff-only** until a curator reviews and publishes them; everyone else imports public. Portraits are matched to a face automatically when exactly one confident match is found.
- **Creator names link to person records.** Every creator on an imported item resolves to a person by exact name match, so the artifact page can link "Parr, Rachel I." straight to her person page — see [Working with Artifacts](/docs/en-US/guides/working-with-artifacts#creators-link-to-person-pages).
- **PastPerfect's Web Include flag decides public visibility.** A record marked Web Include imports as public; everything else imports non-public (members-or-narrower, per your institution default) — exactly mirroring the publication decisions your museum already made in PastPerfect, so a 50,000-item import doesn't dump unreviewed material onto your public site.
- **Images PastPerfect flags RESTRICTED stay staff-only**, invisible to the public even though the artifact itself may otherwise be public. This is currently the only way to set per-asset visibility in Preservated — see [Per-asset visibility](/docs/en-US/guides/collections-and-permissions#per-asset-visibility-staff-only-attachments) in Collections and Visibility.
- **Multimedia attachments** (audio, documents, video linked to a catalog record) come in as labeled supplemental assets on the artifact, not as separate items.
- **The `collection` field seeds the Collections mapping grid** automatically, exactly like any other source.

Toggle whether to import people, creators, and sites on the Source step (each defaults on). The Map Fields step shows PastPerfect's fixed mapping read-only, the same as other built-in sources.

### Import a Library of Congress Free-to-Use dataset

The Library of Congress publishes curated public-domain photo sets as downloadable "Free to Use and Reuse Sets" packages (README, `metadata.jsonl`, a manifest, and a `data/` folder of images). Drag that folder onto the Source step and Preservated recognizes it from the README and manifest, showing a **"Library of Congress — Free to Use and Reuse Sets"** badge with matched/missing file counts.

Preservated picks `metadata.jsonl` automatically among the redundant metadata formats in the package, and matches each record to its image using the manifest rather than guessing from filenames — so the one record whose file lives in a nested folder still matches correctly.

At the Import Options step, choose how to source the images:

- **Use local files from the package (recommended)** — imports the featured image already included in the download. Fast, and enough for most use.
- **Download high-resolution originals from loc.gov** — fetches the full-size master (often a TIFF) for each item directly from the Library of Congress during background processing, instead of using the smaller file in the package. This is slower — it runs as background work per item rather than during upload — and if a specific item's high-res original can't be resolved, Preservated falls back to the largest preview image available rather than failing the item.

Use the existing **Record range** control for a trial run — set it to the first 25 records, for example, and only those 25 image files upload, not the whole set. The 72 curated Sets in the package seed the Collections mapping grid automatically. Items already imported from the Library of Congress through the older URL-based import are recognized as duplicates, so importing the same item both ways never creates two artifacts.

### Very large imports

A PastPerfect export with tens of thousands of catalog items is too much for one import session to hold safely in your browser tab. When a recognized package's item count is large enough, Preservated automatically splits it into a **group of sessions** of up to 2,000 items each, labeled "(part 1 of 12)" and so on, and uploads and creates them one at a time in sequence.

While a grouped import runs:

- Keep the browser tab open — a banner reminds you while parts are still uploading. Each part's files upload just before that part is created, so nothing sits waiting for hours.
- The import sessions page groups all the parts under one collapsible entry with an aggregate progress bar, alongside your other sessions.
- If your browser or connection drops partway through, **re-run the same import from the same folder**. Already-imported items are recognized as duplicates and skipped automatically, so re-running resumes safely from wherever it stopped rather than creating duplicates.

## Map Fields

The Map Fields step is where you decide what each artifact gets. It has three parts, top to bottom: **Collections**, **Identifiers**, and the field-mapping table.

### Route collections

If the source records name a collection, the **Collections** panel lists each distinct collection found — with how many records carry it — plus a **Not in a collection** row for the rest. For each one, choose where its records go:

- an **existing** collection,
- a **new collection** (the name defaults to the source value; edit it if you want), or
- **not in a collection**.

A source collection whose name already matches one of yours is pre-selected to that existing collection. If the source has no collection data, the panel just lets you decide where the uncollected records land. Records keep their source collection name in their preserved metadata regardless of where you route them.

### Choose how objects are numbered

The **Identifiers** panel decides the accession number each imported object receives:

- **Assign new accession numbers** (the default) allocates fresh numbers from your registry. Choose the **accession, loan, or temporary** group they belong to — new numbers are allocated under it — or create one inline, exactly as on the New Artifact page. The **Keep source id** checkbox (on by default) stashes each item's original number under its `sourceIdentifier` attribute and keeps a link back to the source record when the importer captured one — so renumbering never loses the source's own number, and you can credit the source publicly via **Settings → Access & Discovery**.
- **Keep source id** registers the identifier the source already provides.
- **Keep + prefix** registers the source id behind a prefix you set.

The **On collision** option decides what happens when a number is already taken: append a suffix, skip the item, or fail it. See [Identifiers and Numbering](/docs/en-US/guides/identifiers-and-numbering).

### Map the fields

The table lists **every field found in the source** and how it maps onto an artifact field. Each row has three controls:

- **Use** — uncheck any field you don't want applied. Fields marked **required** stay on because the import needs them for duplicate detection, provenance, or source identity.
- **Transform** — how the value is written: **copy** it as-is, **first with a value** across several source fields, **append** a second value onto the same field, **split** a delimited string into a list, **join** a list into text, or take the **first list item**. When you point a second field at a target that's already mapped, the transform defaults to **append** so both values are kept rather than one overwriting the other (prose joins with a blank line, identifiers with "; ").
- **Artifact field** — type to find any target: a core field (title, description, date, identifier, creators, subjects, places, rights, …), an **archival attribute** (extent, container, photo number, and similar — these live in the record's attributes alongside the standard fields), one of your institution's custom fields, or a field from any of the built-in field packs. Mapping a pack field your institution hasn't added yet **adds it on import** (copy-on-map), so the value has somewhere to live.

Some rows on a built-in source carry **source provenance** (where the record came from) or a smart, source-specific transform. Those are shown so you can see what happens, but they aren't editable.

Hover any source field to preview its first values and which record each came from — useful for confirming a column holds what you expect before you map it.

Use **Add field** to write a **fixed value** to every imported record — for example, stamp a known genre or rights statement that the source data doesn't carry. The left side becomes a value box; the value is copied to the field you choose on every record.

Unchecking a field only affects what is written to artifact fields. The complete source record, provider identity, and external identifiers are always preserved so you can re-map or audit later.

:::note
Built-in sources such as the Cleveland Museum of Art map through a fixed, whole-collection pipeline. Their rows show exactly what each artifact will receive and can be unchecked, but their targets and transforms aren't editable.
:::

## Start from a saved mapping or preset

For a generic CSV/JSON import, you rarely need to map columns from scratch. Above the field list, **Start from a saved mapping or preset** offers two kinds of starting point:

- **Migration presets** — built-in starting mappings for the systems museums migrate from most often: PastPerfect, eHive, TMS / CDWA-Lite, CONTENTdm (OAI-DC), CollectiveAccess, a generic Dublin Core CSV, and **Preservated (qualified-DC round-trip)** for re-importing your own exported records. Pick the one that matches your export and Preservated pre-fills the targets for the columns it recognizes by name. The preset is a starting point you then edit — it never changes your data on its own.
- **Saved mappings** — mappings your institution saved from an earlier import (see below).

Applying a preset or saved mapping only fills the columns it recognizes; anything it doesn't mention keeps the wizard's own best-guess target, and a custom field a preset references but your institution hasn't added is left for you to map. Choosing one also restores the duplicate-handling and numbering choices saved with it, which you can still change in Import Options.

Presets map standard columns to artifact fields and to a few add-on fields like credit line and provenance. Controlled vocabulary — object name, medium, culture — is left for you to map, because those belong to your [authority-linked subjects](/docs/en-US/guides/custom-fields), not a free-text column.

### Rebinding to existing authorities (round-trip)

When an imported value already carries an authority link — a vocabulary identifier (URI) and scheme, as Preservated's own export does and many other systems do — Preservated **rebinds it to that same authority** instead of creating a duplicate local term. A column whose values are plain labels can still be rebound when the mapping records which vocabulary the column belongs to (for example, the Preservated round-trip preset hints the subject column to LCSH): each label is checked against that authority and linked on an exact match, and left as a local term otherwise. This means exporting from Preservated and importing back — or moving records between authority-aware systems — keeps your controlled vocabulary intact rather than multiplying near-duplicate terms.

### Save a mapping for next time

Once the field list looks right, an administrator can choose **Save as mapping**, give it a name, and reuse it on the next import of the same source. A saved mapping stores the `column → field` choices, your excluded fields, and the duplicate-handling and numbering policy — so a recurring monthly export becomes a one-click setup. Saved mappings are shared across your institution; applying one is available to any editor, while creating, editing, or deleting them is limited to administrators.

## Import Options

Import Options ask the same decisions in the same order for every source:

- **Record range** — import a subset for a trial run, or leave the count blank to import everything.
- **Data overrides** — how to treat records that were already imported: **skip exact duplicates** (the default), **fill empty fields** on unedited duplicates without overwriting your edits, or **always create new**.
- **Asset source** — for a file-package upload, this step is skipped: the files you selected (and matched, if applicable) already are the asset source, decided back on the Source and Reconcile steps. For a URL source, choose **remote download** (fetch images from their source URLs) or **metadata only** (text records with no assets).
- **AI analysis** — run AI analysis on imported assets and auto-apply confident suggestions to empty fields (on by default when the source supports it). A second checkbox, **Transcribe audio & video**, is off by default — turn it on to also transcribe any audio or video files, which draws on your institution's AI credit balance per minute of media.
- **Museum-vision / derivatives / enrichment** — whether to run background enrichment on the imported items.

Numbering moved to the **Identifiers** panel on the Map Fields step (above) — set it there.

:::tip
Numbering is a per-import decision. A Library of Congress batch and a local accession batch can use different numbering in the same institution — choose it on the Map Fields step, not in a global setting.
:::

## How items are processed

When you select **Create import session**, the Review step reports each stage as it happens — uploading files (only when the import carries local files), creating records, then starting the import. Preparing a large batch of records can take a moment; the status line tells you what the wizard is doing and, for metadata-only and URL imports, confirms that no images upload at this stage — those are downloaded later, during processing. Very large imports that split into multiple sessions show a per-part list instead.

After you submit, the session page separates record import from the background work that follows it:

- **Records** — each item moves through **pending → queued → processing → completed** (or **failed**, with the error recorded on the item).
- **Assets and derivatives** — masters are stored and viewer tiles, page renders, and media proxies are generated.
- **Enrichment** — AI analysis, museum-vision, OCR, and related work run last.

Records can finish while assets and enrichment are still catching up. When that happens, the session shows a secondary line such as "All records imported. Background work: 12 images still generating viewer tiles" — on both the session page and its card in the import list. While an import is active, the page shows a recalculating estimate ("Estimating…", then "~3 min remaining").

:::tip
Imports are designed to be left alone. Close the tab, come back later — the session keeps processing on the server and the page shows live progress when you return.
:::

## Metadata mapping

What arrives on each artifact depends on the source:

- **File uploads** get technical metadata from the file itself: EXIF capture dates become artifact dates, GPS coordinates become capture locations, and the filename seeds the title.
- **Metadata-file imports** map columns or record fields into artifact metadata, assets, identifiers, rights, and source provenance.
- **External archive imports** map the source's descriptive metadata: title, date, creator, culture, collection, subjects, object type, dimensions, inscriptions, credit line, identifiers, and rights statements where the provider exposes them.

Provider-specific fields that do not have a shared artifact field are still preserved as source metadata. Everything is editable afterward, and [AI analysis](/docs/en-US/guides/ai-analysis) can fill gaps the source left empty.

### Long titles are shortened automatically

Artifact titles hold up to 500 characters. Some sources — Library of Congress records especially — occasionally ship a title longer than that, and an import never fails because of one. Instead:

- The stored title is shortened to fit, cut at a word boundary near the limit and ended with an ellipsis (…).
- The **full original title is preserved** as an alternative title on the artifact, and search finds the record by either version.
- The wizard warns you before the import starts — the source analysis lists how many records will be affected — so an unexpected count is a signal to check your field mapping rather than a surprise afterward.

Nothing in the preserved source record changes: the raw metadata Preservated keeps for auditing and re-mapping always carries the title exactly as the source sent it.

## Import API batches

Some external sources expose search APIs instead of one fixed collection URL. Adapters for those providers import a numbered batch from the pasted API URL.

The Cleveland Museum of Art importer uses this model:

1. Paste a CMA URL — an Open Access `/api/artworks/` search URL, a single-artwork API URL, a human-facing `clevelandart.org/art/{accession}` page, or a collection search URL copied straight from your browser (for example `clevelandart.org/art/collection/search?search=philadelphia&cc0=1`). Preservated translates the search page's filters to the Open Access API, mapping the free-text box to the API search and forwarding recognized filters like open-access, on-view, department, and type; any filter without an API equivalent is dropped and called out in a warning. You can also upload a CMA JSONL/NDJSON/JSON export instead.
2. In **Import Options**, choose a batch number and batch size, then select **Apply & re-fetch**.
3. Preservated requests the matching page of records and creates one import item per artwork.

Batch numbers are one-based and the batch size defaults to 100 (the provider cap). Batch 1 imports the first 100 results, batch 2 the next 100, and so on. If your pasted URL already includes `skip` and `limit`, those are honored as-is. Each batch is its own session with its own history and retry state, which makes trial imports and larger migrations easier to verify.

:::tip
Many CMA artworks have several views, and each view comes in multiple resolutions. Preservated brings in **every** view as its own image on a single artifact — full resolution by default (the master, often a large TIFF). To save bandwidth, uncheck **Download full-resolution images** in Import Options to fetch the smaller display-resolution images instead.
:::

## Handle failures and retries

Open a session to see its items in a dense table — each row shows the title, status, a link to the created artifact, the source link, asset/derivative and enrichment state, and the latest error. Use the status filters above the table to jump to **Failed**, **Processing**, or **Background** items. For failed items:

1. Check the error message on the item's row — unsupported formats and network timeouts are the most common causes.
2. Fix the cause (convert the file, check the source URL).
3. Use **Retry** on the row to requeue just that item, or **Retry All** to requeue every failed item.

Error messages on failed items name the actual problem — a value too long for a field, a duplicate value, or a related record that no longer exists — rather than surfacing raw technical output.

If the whole session stalls, check the worker status banner at the top of the import pages. The background worker must be running for any processing to happen.

### When the import can't even start

Submitting an import or uploading a file can also fail before any session exists — a dropped connection, an expired sign-in, a file too large for the server, or a temporary service outage. These failures now say exactly what happened instead of a generic "something went wrong":

- **"…returned HTML instead of JSON (HTTP 504)"** — a gateway or proxy answered instead of Preservated; the service was briefly unreachable. Try again in a moment.
- **"Your session appears to have expired"** — sign in again, then retry. Nothing was created.
- **"The upload is too large for the server to accept (HTTP 413)"** — reduce the selection size and retry.
- **"The service is temporarily unavailable"** — background infrastructure is restarting or unreachable; retry shortly.

Many of these messages include a **Request ID**. If a failure persists, include that ID when you contact support — it lets us find the exact server-side log line for your request.

## Large migrations

A few practical notes for imports in the thousands of items:

- Import in batches by donor, decade, series, search result page, or API batch number - smaller sessions are easier to verify and retry.
- Watch the first hundred items before committing the rest; metadata mapping issues show up early.
- File formats outside the common set are listed in [Supported File Formats](/docs/en-US/reference/supported-file-formats); convert exotic formats before importing.
- Keep the original export or API URL with the migration notes. Preservated stores source identifiers and provider provenance on imported records, but the original source is still useful for audits.