How do I define custom fields?

Requires Pro

Quick answer

You create custom fields in the Data module via the “Fields” button of the relevant object type — with Key, Label, Field Type, optional Options, and the Required Field flag. For assets (and other system objects), you manage custom fields under Catalog & Checkout → the “Custom fields” tab with Object Type = asset.

Prerequisites

Required role Administrator, Manager, or Technician

— the Admin, Manager, and Technician roles can create and change custom fields; only the Administrator can delete them. Programmatically, the API token needs the write scope.

Custom fields require Pro or higher (the custom_fields feature). Without the feature, the “Custom fields” tab shows the message “Custom fields are available from the Pro plan.” and the API responds with 403.

The field types

Field type	Meaning / input
text	Free text (default)
number	Number
boolean	Yes/No (checkbox)
date	Date
select	Single select — enter options comma-separated
multiselect	Multi-select — enter options comma-separated
url	Web address
currency	Monetary amount
user	Reference to a user of the tenant
relation	Reference to a record of another object type — enter the target type’s key in the “Options / Relation Target” field

Instructions

GUI (web interface)

1. Open the fields dialog. In the Data module, select the object type and click “Fields”. The dialog shows the existing fields as chips (with their field type) and, below that, the form for new fields.

   Screenshot pending katalog-freifelder-01 'Fields' dialog for an object type with field chips and the Key, Label, Field Type, Options, and Required Field form

   The fields dialog: existing fields as chips, with the creation form below.

2. Define the field. Fill in:

   • Key (e.g. plate) — lowercase letters, digits, and underscores only.
   • Label (e.g. “License Plate”) — the display name shown in the form.
   • Field Type — see the table above.
   • Options / Relation Target — for select/multiselect, the values comma-separated (e.g. Gasoline,Diesel,Electric); for relation, the key of the target object type.
   • Required Field — check this if the value is required on every record.

   Click “Add field”.

3. Custom fields for assets. Open Catalog & Checkout → the “Custom fields” tab. Here you manage custom fields for any object type — enter asset as the Object Type, for example, so the field appears in the asset form (in the Custom Fields section).

   Screenshot pending katalog-freifelder-02 'Custom fields' tab under Catalog & Checkout with the custom field list and the creation form

   Custom fields for assets and other object types: the 'Custom fields' tab.

API (curl)

A POST to /api/v1/custom-fields (scope write). entity_type is the object type’s key — asset for asset fields:

Create a select field for a custom object type

curl -X POST https://demo.notory.io/api/v1/custom-fields \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "vehicle",
    "name": "fuel",
    "label": "Antrieb",
    "field_type": "select",
    "options": "Benzin,Diesel,Elektro",
    "required": true
  }'

Response (201 Created, truncated)

{
  "id": "5b8d1e20-9c3f-4a7b-b2e6-0d4f8a1c7e33",
  "tenant_id": "3d9b0c12-4e5a-4f88-b1c7-2a9e6d4f0011",
  "entity_type": "vehicle",
  "name": "fuel",
  "label": "Antrieb",
  "field_type": "select",
  "options": "Benzin,Diesel,Elektro",
  "required": true
}

A custom field for assets — it then appears in the asset form:

'Kostenstelle' custom field for assets

curl -X POST https://demo.notory.io/api/v1/custom-fields \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "asset",
    "name": "cost_center",
    "label": "Kostenstelle",
    "field_type": "text"
  }'

List, update, delete (deleting requires the Administrator role):

List all custom field definitions

curl -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/custom-fields

Update a field (e.g. remove the required flag)

curl -X PUT https://demo.notory.io/api/v1/custom-fields/5b8d1e20-9c3f-4a7b-b2e6-0d4f8a1c7e33 \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{ "required": false }'

Possible errors: 403 (plan below Pro or missing role), 404 (“Custom field not found”), 422 (validation error, e.g. an empty name).

What happens behind the scenes?

• Effective immediately: New fields appear in the forms right away — for object types, in the record form; for entity_type = asset, in the asset form under Custom Fields and in the asset detail view.
• Validation: When saving records and assets, Notory checks the values passed against the definitions — wrong types, unknown options, or missing required fields result in 422 with an error message per field.
• Tenant isolation: Definitions only apply to your tenant.
• Deleting removes the definition, not the values: Values already saved in existing records/assets remain in the data, but without a definition they’re no longer offered as a form field.
• Foundation for the scanner: The Scan module uses custom fields as the code field (e.g. serial, plate) and quantity field (number/currency) — sensibly named fields pay off there.

Related topics

• Create an object type
• Maintain records — custom fields in action
• Create an asset — custom fields in the asset form
• Scan & Stocktake — code and quantity fields