Imports

Reads rows rows from an uploaded file, maps each spreadsheet column to an ontology property, and creates a passport per row under target. Build the mapping from the file preview, then poll the returned import until its status is terminal. Returns 201 with the import in pending. Requires imports:write. Accepts an optional Idempotency-Key header.

Required attributes

Optional attributes

What a column can feed

Only properties that hold a value import: short_text, long_text, number, boolean, date, tags, range, measurement, file and image. A column mapped to a category divider or a computed composite is ignored.

A mapped column writes the property in the ontology's default language. Translatable properties (short_text, long_text, tags and file) get their other languages through PATCH /v1/passports/{passport} once the passports exist; a mapping target is a bare property id, so property_capacity@de is refused as an unknown property.

Multi-level imports read one worksheet per level

With more than one levels entry the import runs in phases, and phase N reads worksheet N — levels[0] from the first sheet, levels[1] from the second, and so on. The worksheet is fixed by the level's position and cannot be chosen. Two consequences:

• A workbook with fewer sheets than levels entries imports zero rows for every level past the last sheet, and the import still finishes complete. Check total_rows against what you expected.
• Column 0 is special regardless of mapping: on the parent level it is the passport's friendly_id, and on every child sheet it is the reference to the parent row.

The file preview lists sheets in workbook order — use it to confirm the order matches your levels.

Lists the team's imports, latest first. Returns a paginated list. Requires imports:read; a key whose imports:read is restricted to specific ontologies cannot use this team-wide list (403 ability_not_scoped_to_resource) — fetch imports by id instead.

List rows come from an index that carries neither the mapping nor the per-failure counters, so each row is a reduced shape: object, id, target, status, total_rows, processed_rows, metadata and created_at — the one place an import reports when it was created. Fetch by id for the full object.

Optional attributes

The creation window runs as a SQL WHERE rather than a scan, so pages stay exact. Filters join the cursor's scope; see pagination.

Retrieves one import by id, with live progress counters. Poll it until status is complete, complete_with_errors, or failed. Requires imports:read.

Before workers start finishing, dispatched_rows is the counter that moves; after that, processed_rows + failed_rows against total_rows is the progress, and phases breaks it down per level.

Lists an import's per-row outcomes, so you can see exactly which rows failed and why. Filter with status; passing status=failed selects both validation and infrastructure failures. Requires imports:read.

Pages hold a fixed 100 rows and this endpoint takes no limit — page with cursor until has_more is false. Beside the list envelope the response carries header — one {index, label, property_id} entry per column, property_id being null on an unmapped one — and the mapping, for rendering rows back to their columns.

Optional attributes

Returns the failed rows as text/csv, not JSON — the 200 body is the file itself, not an envelope. Requires imports:read. It is served as an attachment named {import_id}_failed_rows.csv.

The file holds both kinds of failure — rows rejected by validation and rows lost to an infrastructure error — one row each, laid out in the import's own column order, plus a trailing Errors column holding that row's failures as Property: message fragments joined by ; . You get the original cells and the reason side by side, which is the whole point: the sheet is repairable in place.

An import with no failed rows returns a header-only file — not a 404, and not an empty body. A consumer can treat "one line" as "nothing to fix" without special-casing an error status.

The byte-order mark

The file is UTF-8 with a BOM, deliberately. It exists to be opened in a spreadsheet, and Excel reads a BOM-less UTF-8 CSV as the local 8-bit codepage, mangling every non-ASCII character in it — an ontology with a °C unit or a supplier name carrying an accent comes out as mojibake for the very people the export is for.

The cost lands on programmatic consumers instead: strip the BOM before reading the first header cell, or your first column will not match by name. It is the single most common cause of a header lookup that mysteriously fails on column one only.

When to use it

If you are handling failures programmatically, use GET /v1/imports/{import}/rows instead — it returns the same rows as JSON, with structured per-property errors, no BOM and no CSV parsing in the way.

This endpoint exists because in practice the people who repair import failures work in a spreadsheet. Export the failures, fix the cells where they already live, then feed the corrections back through retry — the retry payload takes column index → corrected value, which maps directly onto the columns you just edited.

Retries an import's failed rows, optionally with inline cell corrections. Supply rows — each entry pairs a row_id with a corrected_row that maps a column index to a fixed value — and/or scope: "infra_all" to re-run every infrastructure failure without listing them. Send at least one of the two; an empty body is 400 parameter_invalid. Requires imports:write. Accepts an optional Idempotency-Key header.

Corrections are re-validated server-side first. The response sorts every row you named into one of three lists:

• dispatched — re-queued; the row moves to retrying.
• still_invalid — failed re-validation, returned with its errors and not dispatched. A child-level row whose parent never imported comes back here with code parent_unresolved: retry the parent row first.
• skipped — no such row, or one that is not in a failed state any more (already retrying, or done).

Optional attributes