How CSV Import Works
This guide explains how to fill your CSV so it maps correctly to form fields in the Import tool.
- Each row in the CSV = one record.
-
Each column header should match the form field
nameor follow the special patterns below.
1. Basic Text Fields
For fields of type text, textarea,
html, editor or chip, put
the text directly in the cell.
Form field config
{ "type": "text", "name": "fieldName" }
CSV example
| fieldName |
|---|
| Sample Text |
2. Email Fields
Use a valid email address. Invalid emails will be flagged.
| emailAddress |
|---|
| user@example.com |
3. Number Fields
Insert only numbers. Commas for thousands are allowed.
| totalCount | usedCount | remainingCount |
|---|---|---|
| 1,000 | 750 | 250 |
Non-numeric values will show as errors.
4. Boolean / Switch Fields
Accepted values (case does not matter):
- true
- 1
- yes
- y
- on
- false
- 0
- no
- n
- off
| isActive |
|---|
| yes |
5. Date Fields
The importer parses the value into an ISO date.
Supported formats include:
yyyy-MM-dd→2025-03-31dd/MM/yyyy→31/03/2025MM/dd/yyyy→03/31/2025
| startDate |
|---|
| 2025-03-31 |
If a field has a specific dateFormat, that format is
used first.
6. Select / Radio / Autocomplete Fields
These fields use a fixed list of options. You can usually put either the value or the label. Matching ignores case and whitespace.
Simple options
{ "type": "select", "name": "status", "options": ["Active", "Inactive"] }
| status |
|---|
| active |
“active”, “Active” or “ ACTIVE ” all match the same option.
Object options
{ "type": "select", "name": "priority", "options": [ { "value": "high", "label": "High" }, { "value": "low", "label": "Low" } ] }
You can use either high or High in
the CSV.
If the option is not found and create is not
allowed, you get an “Invalid option” error.
7. Lookup / Linked Fields
Some select or autocomplete fields link to other collections (like users, projects, items). These use a web lookup behind the scenes.
In the CSV, you normally put the code or label that identifies the related record.
CSV example
| linkedItemCode |
|---|
| ITEM001 |
Use the same codes that your system already uses.
How it is stored
{ "$type": "lookup", "$collection": "items", "$customer_id": "CUSTOMER1", "$code": "ITEM001", "$label": "Item Name" }
8. Multiple Fields (Repeating Groups)
Fields with type: "multiple" represent an array of
entries, like a small table inside each record.
Config example
{ "type": "multiple", "name": "lineItems", "fields": [ { "type": "text", "name": "label" }, { "type": "number", "name": "amount" } ] }
Stored value
"lineItems": [ { "label": "Item A", "amount": 100 }, { "label": "Item B", "amount": 200 } ]
8.1 JSON in a Single Cell
Put a JSON array (or object) in the cell. The importer parses it into entries.
| recordId | lineItems |
|---|---|
| REC001 |
[ {"label":"Item A","amount":100}, {"label":"Item
B","amount":200} ]
|
8.2 Dot Notation Columns
Use one column per index and field:
lineItems.0.label, lineItems.0.amount,
etc.
| recordId | lineItems.0.label | lineItems.0.amount | lineItems.1.label | lineItems.1.amount |
|---|---|---|---|---|
| REC001 | Item A | 100 | Item B | 200 |
8.3 Shorthand with | and -
Use | to separate entries and - to
separate fields inside one entry. Fields follow the order in the
config.
| recordId | lineItems |
|---|---|
| REC001 | Item A-100|Item B-200 |
This becomes:
"lineItems": [ { "label": "Item A", "amount": 100 }, { "label": "Item B", "amount": 200 } ]
Single subfield multiple
If the multiple field has only one subfield, each token becomes one entry.
{ "type": "multiple", "name": "tags", "fields": [{ "type": "text", "name": "label" }] }
| tags |
|---|
| New|Featured|Archived |
"tags": [ { "label": "New" }, { "label": "Featured" }, { "label": "Archived" } ]
9. Required Fields & Missing Columns
Required form fields must either:
- Have a column in the CSV with a non-empty value, or
- Be filled manually in the preview grid before importing.
If a required column is missing, the importer shows a “Missing required columns” message and adds the column in the preview so you can fill it in.
10. Compact Example with Multiple Fields
Here is a compact CSV layout that uses the shorthand format for a generic record with multiple line items.
| recordId | period | totalCount | usedCount | remainingCount | lineItems |
|---|---|---|---|---|---|
| REC001 | Jan-25 | 30 | 28 | 2 | Item A-100|Item B-200 |
You can switch between shorthand, dot notation, or JSON depending on what feels easiest for your use case.