How do I create a custom object type?

Requires Pro

Quick answer

Open the Data module, click “New type”, give it a key (machine name, e.g. vehicle) and a label (e.g. “Vehicle”), and confirm with “Create”. Afterward, you define the custom fields for the type — only then can you start capturing records.

Prerequisites

Required role Administrator

— creating, changing, and deleting object types is reserved for administrators. Any logged-in user can then maintain records for existing types. Programmatically, the API token needs the write scope.

The Flex platform requires Pro or higher (the custom_fields feature). On lower plans, the API responds with 403 and an upgrade notice.

Instructions

GUI (web interface)

1. Open the “Data” module. Select Data in the left-hand navigation. The “New type” button is in the top right. If there are no types yet, the page shows the message “No object types yet. Create one to get started.”

2. Define the type. In the “New type” dialog, fill in two fields:

   • Key (machine name) — lowercase letters, digits, and underscores only (e.g. vehicle). The key is the technical identifier and cannot be changed later.
   • Label — the display name (e.g. “Vehicle”).

   Click “Create”.

   Screenshot pending katalog-objekttyp-01 'New type' dialog with the Key (machine name) and Label fields

   The 'New type' dialog: key and label are enough.

3. Add fields. The new type appears as a selectable chip. The table is still empty and prompts you: “Add at least one field to this type first.” — continue with Define custom fields.

   Screenshot pending katalog-objekttyp-02 Data page with the newly created object type as a chip and an empty table noting the missing fields

   After creating it: the type exists but still needs fields.

API (curl)

A POST to /api/v1/object-types (Administrator role, scope write). key (pattern ^[a-z0-9_]+$, max. 64 characters) and label are required; label_plural, description, icon, and color are optional:

Create object type

curl -X POST https://demo.notory.io/api/v1/object-types \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "vehicle",
    "label": "Fahrzeug",
    "label_plural": "Fahrzeuge",
    "description": "Firmenfahrzeuge und Poolwagen",
    "color": "#c6703d"
  }'

Response (201 Created)

{
  "id": "0c9e2b74-5a1f-4d3e-8b6c-7f2a9d4e1c00",
  "key": "vehicle",
  "label": "Fahrzeug",
  "label_plural": "Fahrzeuge",
  "description": "Firmenfahrzeuge und Poolwagen",
  "icon": null,
  "color": "#c6703d"
}

List all types, rename a type, or delete one:

List types

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

Change the label (the key stays fixed)

curl -X PUT https://demo.notory.io/api/v1/object-types/0c9e2b74-5a1f-4d3e-8b6c-7f2a9d4e1c00 \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Dienstfahrzeug" }'

Delete type (response: 204 No Content)

curl -X DELETE -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/object-types/0c9e2b74-5a1f-4d3e-8b6c-7f2a9d4e1c00

Possible errors: 403 (no Administrator role or plan below Pro — message: “The Custom fields module is not included in the ’…’ plan”), 422 (invalid key, e.g. uppercase letters or spaces).

What happens behind the scenes?

• Tenant assignment: The object type belongs to your tenant; other tenants don’t see it and can maintain their own types with the same key.
• License gating: All object type and record routes are gated behind the custom_fields feature (Pro+) — below that, the API returns 403 with an upgrade notice.
• The key is stable: The key is the reference used by records, custom fields (entity_type), lookups, and the scanner. Only the label, description, icon, and color can be changed (PUT).
• No fields yet = no records: The “Add record” and “Import” buttons stay disabled until the type has at least one custom field.
• Delete with care: When deleting, the interface asks for confirmation (“Delete this object type?”). Only delete a type once its records are no longer needed.

Related topics

• Define custom fields — the next step
• Maintain records
• Scan & Stocktake — count records on the go
• Users & Roles — who is an administrator?