> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinship.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Batch updating — Reference
> Editable and non-editable fields, and guidelines for preparing CSV files for successful batch updating.
This page covers the specific fields, their formatting rules, and reasons for errors you may encounter when batch updating items. For an overview of the batch update process, see [About batch updating items](about-batch-updating).
## Editable fields
These fields are updated when you import a CSV. All other fields are ignored on import.
The Field Name column shows what you see in the Export dialog. The CSV Header column shows the corresponding column name in the exported file.
Most fields are limited to 255 characters, with the exception of Class, which allows 31. If you add more, they will be trimmed when the file is imported.
| Field Name | CSV Header | Items | Materials | Max Characters |
| ------------------- | ------------------- | :---: | :-------: | -------------- |
| Name | `name` | ✓ | ✓ | 255 |
| Description | `description` | ✓ | ✓ | 255 |
| Class | `class` | | ✓ | 31 |
| Keynote | `keynote` | | ✓ | 255 |
| Mark | `mark` | | ✓ | 255 |
| URL — Manufacturer | `manufacturer_url` | | ✓ | 255 |
| URL — Documentation | `documentation_url` | | ✓ | 255 |
## Non-editable fields
These fields can be included in an export for reference but are ignored on import:
| Field Name | CSV Header | Items | Materials | Notes |
| ------------- | ---------------------------- | :---: | :-------: | ---------------------------------------------------------------------------- |
| ID | `id` | ✓ | ✓ | The item's ID — required for batch updating. |
| Category | `category` | ✓ | | |
| Hosting | `hosting` | ✓ | | The item's hosting (for example, Wall-Based). |
| No. Types | `type_count` | ✓ | | The number of types that exist for the item. |
| Revit Version | `revit_version` | ✓ | ✓ | |
| Manufacturer | `manufacturer` | ✓ | | |
| Size (bytes) | `size_bytes` | ✓ | | |
| Unit System | `unit_system` | ✓ | | Metric or Imperial. |
| URL — Kinship | `kinship_url` | ✓ | ✓ | Link to the item in the Library. |
| No. Projects | `project_count` | ✓ | | Number of projects the item has been placed in. |
| Quantity | `quantity` + `quantity_unit` | ✓ | | The number of instances, area, or length of the item in projects. |
| No. Lists | `list_count` | ✓ | ✓ | The number of Lists the item exists in. |
| Added By | `added_by` | ✓ | ✓ | The team member that added the item to the Library. |
| Date Added | `date_added` | ✓ | ✓ | When the item was added to the Library. |
| Approved By | `approved_by` | ✓ | ✓ | The team member that approved the item, if it was added to Pending Approval. |
| Date Approved | `date_approved` | ✓ | ✓ | When the item was approved. |
| Updated By | `updated_by` | ✓ | ✓ | The team member that last updated the item in the Library. |
| Date Updated | `date_updated` | ✓ | ✓ | When the item was last updated. |
Quantity exports as two CSV columns (`quantity` and `quantity_unit`) controlled by a single checkbox in the dialog. This may be an area, length, or number of instances depending on the item category.
When an item has multiple Revit versions, the Revit Version field shows the lowest available version.
## How values are handled on import
| Behavior | What happens |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Column order | Columns are matched by header name, not position. You can delete, add, or rearrange columns freely. |
| Missing columns | If a column isn't in the CSV, that field is left untouched on every item. |
| Empty cell | Clears the field on the matching item. |
| Empty Name | The row is skipped. Name is the only field that can't be cleared. |
| Empty Class | The material is moved to the Unassigned Class. |
| New Class value | If a Class value doesn't exist yet, it's created automatically and the material is moved to it. |
| Values over the character limit | The value is trimmed to the character limit. |
| Name already in use | Item and material names must be unique within the Library or an individual Collection. A name that clashes with an existing item causes that row to be skipped. |
| Duplicate names within the CSV | The first row is processed. Subsequent rows with the same name are skipped. |
| Invalid values | If any editable field has an invalid value (for example, a non-URL value in a URL field), the entire row is skipped. |
## CSV format
The import accepts a single `.csv` file:
| Requirement | Detail |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| Format and Encording | CSV with comma delimiters (UTF-8). Tab, semicolon, and other delimiters are not supported. |
| Required column | `id` must be present. |
| Required headers | At least one editable field header must be present alongside `id`. |
| Row order on export | Items are exported by Category A–Z, then Name A–Z. Materials are exported by Class A–Z, then Name A–Z. |
## Import statuses
Every import appears on the Batch Updates page with one of these statuses:
| Status | Meaning |
| ---------- | ---------------------------------------------------------------------------------- |
| In Queue | Waiting to be processed. |
| Processing | Updates are being applied. |
| Completed | The import finished. Click the import to see a summary. |
| Failed | An error prevented the import from processing. Click the import to see the reason. |
| No Updates | The file was processed but no items changed. |
## Why an import may fail
If there's a problem with the CSV file itself, the entire import fails and no items are updated. These are the reasons an import can fail, along with the error message shown on the Batch Updates page:
| Reason | Error message |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| The file isn't a valid CSV, or there is no editable field in the header row | "This file doesn't contain valid headers. Export a new CSV and try again." |
| The CSV doesn't include an ID column | "This file is missing the ID column. The ID is needed to match rows to library items." |
| The CSV has duplicate editable column headers | "This file contains duplicate headers. Remove the duplicates and upload again." |
| None of the IDs match items in your Library | "This file does not contain IDs matching any items in your library." |
## Why individual rows may be skipped
If there's a problem with a specific row, that row is skipped and the rest of the import continues.
| Reason | Summary line |
| ----------------------------------------- | --------------------------------------------- |
| The ID doesn't match any item or material | "ID not found in your library or collections" |
| A field contains an invalid value | "Invalid value in \[field name]" |
| The Name field is empty | "Name cannot be empty" |
| The Name is already used by another item | "Duplicate Name in the uploaded file" |
If one of these errors occurs, the entire item is skipped — not just the field with the error.
## Who can export and import
| Role | Export | Import |
| ------------------------------------- | ------ | ------ |
| Content Manager, Administrator, Owner | ✓ | ✓ |
| Team Member | ✓ | ✗ |
## Learn more
* [How to export a CSV file](how-to-export-a-csv) for step-by-step export instructions.
* [How to batch update items by importing a CSV file](how-to-import-a-csv) for step-by-step import instructions.
* [About batch updating items](about-batch-updating) for an overview of how batch updating works.