Custom Fields

Custom Fields let you attach structured metadata to devices that goes beyond the built-in attributes (hostname, OS type, tags, etc.). You define field definitions at the organisation or partner level, then set values on individual devices. This is useful for tracking asset numbers, purchase dates, warranty expiry, department assignments, compliance status, and any other data specific to your environment.

---

How it works

Custom Fields has two layers:

1. Field definitions — created via the /api/v1/custom-fields endpoints. A definition declares the field’s name, key, data type, validation options, and which device types it applies to. Definitions are scoped to either an organisation or a partner.
2. Field values — stored as a JSONB object on each device record (custom_fields column). Values are set by patching the device via PATCH /api/v1/devices/:id with a customFields key-value map. Values are merged with any existing custom fields on the device rather than replacing them.

---

Field types

Every field definition has a type that controls what values are accepted:

Type	Description	Example value
text	Free-form string up to 10,000 characters	"Rack A, Shelf 3"
number	Numeric value (integer or decimal)	42
boolean	True or false	true
dropdown	One of a predefined list of choices	"Finance"
date	Date string	"2026-06-15"

---

Validation options

When creating a field definition you can supply an options object to constrain accepted values:

Option	Applies to	Description
choices	dropdown	Array of allowed string values. Example: ["Finance", "Engineering", "Sales"]
min	number	Minimum numeric value
max	number	Maximum numeric value
pattern	text	Regular expression that text values must match
placeholder	text, number, date	Placeholder hint displayed in the UI

You can also set a defaultValue on the definition. If a device does not have an explicit value for the field, the default is used. Setting required: true indicates that the field should always be populated for applicable devices.

Note

Validation options are stored on the definition for use by the UI and any future server-side enforcement. The current device PATCH endpoint accepts any value that matches the Zod schema (string, number, boolean, or null) without cross-referencing the definition’s options at write time.

---

Device type targeting

A definition can optionally include a deviceTypes array to limit which operating systems it applies to. Accepted values are windows, macos, and linux.

When deviceTypes is omitted or set to null, the field applies to all device types.

{
  "name": "BitLocker Recovery Key",
  "fieldKey": "bitlocker_recovery_key",
  "type": "text",
  "deviceTypes": ["windows"]
}

---

Scoping and multi-tenancy

Field definitions are scoped to one of:

Scope	Who can create	Visibility
Organisation	Organisation-scoped users or partner users with access to the organisation	Visible only within that organisation
Partner	Partner-scoped users	Visible to the partner and all organisations the partner can access

Caution

You must provide either orgId or partnerId when creating a field — not both. The API returns a 400 error if both are supplied. For organisation-scoped users the orgId is automatically inferred from the authentication context.

Access rules

• Organisation users see definitions scoped to their own organisation plus any definitions scoped to their parent partner.
• Partner users see definitions scoped to their partner plus definitions scoped to any organisation they can access.
• System-scoped users see all definitions.

Editing and deleting a definition requires ownership: organisation users can only modify definitions belonging to their organisation, and partner users can only modify definitions belonging to their partner.

---

Creating a field definition

1. Choose a human-readable name (1—100 characters) and a machine-readable fieldKey. The key must start with a lowercase letter and contain only lowercase letters, digits, and underscores (regex: ^[a-z][a-z0-9_]*$).

2. Pick a type from the supported list: text, number, boolean, dropdown, or date.

3. Optionally set options, required, defaultValue, and deviceTypes.

4. Send the request:

cURL

curl -X POST /api/v1/custom-fields \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Department",
    "fieldKey": "department",
    "type": "dropdown",
    "options": {
      "choices": ["Finance", "Engineering", "Sales", "Support"]
    },
    "required": true
  }'

Response

{
  "data": {
    "id": "a1b2c3d4-...",
    "orgId": "org-uuid-...",
    "partnerId": null,
    "name": "Department",
    "fieldKey": "department",
    "type": "dropdown",
    "options": {
      "choices": ["Finance", "Engineering", "Sales", "Support"]
    },
    "required": true,
    "defaultValue": null,
    "deviceTypes": null,
    "createdAt": "2026-02-18T12:00:00.000Z",
    "updatedAt": "2026-02-18T12:00:00.000Z"
  }
}

---

Setting values on devices

Custom field values live in the custom_fields JSONB column on the devices table. To set or update values, send a PATCH request to the device endpoint with a customFields object whose keys correspond to field keys:

curl -X PATCH /api/v1/devices/<device-id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customFields": {
      "department": "Engineering",
      "asset_number": "AST-2026-0042",
      "purchase_date": "2025-11-01"
    }
  }'

Note

Values are merged with existing custom fields. If a device already has {"location": "HQ"} and you patch with {"department": "Engineering"}, the result is {"location": "HQ", "department": "Engineering"}. To remove a field, set its value to null.

Accepted value types

The device update endpoint validates each custom field value against this schema:

Allowed type	Notes
string	Maximum 10,000 characters
number	Integer or decimal
boolean	true or false
null	Removes the field from the device

---

Querying and filtering

Listing field definitions

GET /api/v1/custom-fields returns all field definitions visible to the authenticated user. Query parameters:

Parameter	Type	Description
type	string	Filter by field type (text, number, boolean, dropdown, date)
orgId	UUID	Filter to a specific organisation (must be accessible)
deviceType	string	Filter definitions applicable to a device type (windows, macos, linux)
search	string	Case-insensitive search across field name and fieldKey
page	number	Page number (default: 1)
limit	number	Results per page (default: 50, max: 100)

curl "/api/v1/custom-fields?type=dropdown&search=department" \
  -H "Authorization: Bearer <token>"

Filtering devices by custom field values

Custom field values are stored as JSONB on each device. In the current implementation, device list queries (GET /api/v1/devices) do not directly filter by custom field values in query parameters. To find devices with specific custom field values, retrieve the device list and filter client-side, or use PostgreSQL JSONB queries if you have direct database access.

---

Updating a field definition

Use PATCH /api/v1/custom-fields/:id to update a definition. You can change name, options, required, defaultValue, and deviceTypes. The fieldKey and type are immutable after creation.

curl -X PATCH /api/v1/custom-fields/<field-id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "choices": ["Finance", "Engineering", "Sales", "Support", "Operations"]
    }
  }'

Caution

Changing options.choices on a dropdown field does not retroactively validate existing device values. Devices that already have a value not in the updated choices list will retain that value until manually corrected.

---

Deleting a field definition

DELETE /api/v1/custom-fields/:id removes the definition. This does not automatically remove corresponding values from the custom_fields JSONB on existing devices — those values become orphaned but remain on the device record until explicitly cleared.

curl -X DELETE /api/v1/custom-fields/<field-id> \
  -H "Authorization: Bearer <token>"

---

Audit logging

All mutating operations on custom field definitions are recorded in the audit log:

Action	Trigger
custom_field.create	A new field definition is created
custom_field.update	A field definition is modified (logs which fields changed)
custom_field.delete	A field definition is deleted

Device-level custom field value changes are logged under the device.update audit action when the device is patched.

---

API reference

All endpoints require authentication and an appropriate scope (organization, partner, or system).

Field definitions

Method	Path	Description
GET	/api/v1/custom-fields	List field definitions (paginated, filterable)
GET	/api/v1/custom-fields/:id	Get a single field definition
POST	/api/v1/custom-fields	Create a new field definition
PATCH	/api/v1/custom-fields/:id	Update a field definition
DELETE	/api/v1/custom-fields/:id	Delete a field definition

Device values

Method	Path	Description
PATCH	/api/v1/devices/:id	Set custom field values (include customFields in request body)
GET	/api/v1/devices/:id	Returns the device with customFields in the response
GET	/api/v1/devices	Lists devices; each includes its customFields object

Create field definition request body

{
  name: string;          // 1-100 characters
  fieldKey: string;      // 1-100 chars, regex: /^[a-z][a-z0-9_]*$/
  type: "text" | "number" | "boolean" | "dropdown" | "date";
  options?: {
    choices?: string[];  // For dropdown type
    min?: number;        // For number type
    max?: number;        // For number type
    pattern?: string;    // Regex for text type
    placeholder?: string;
  };
  required?: boolean;    // Default: false
  defaultValue?: unknown;
  deviceTypes?: ("windows" | "macos" | "linux")[];
  orgId?: string;        // UUID - omit for org-scoped users
  partnerId?: string;    // UUID - omit for partner-scoped users
}

Update field definition request body

{
  name?: string;         // 1-100 characters
  options?: {
    choices?: string[];
    min?: number;
    max?: number;
    pattern?: string;
    placeholder?: string;
  };
  required?: boolean;
  defaultValue?: unknown;
  deviceTypes?: ("windows" | "macos" | "linux")[] | null;
}

---

Database schema

Field definitions are stored in the custom_field_definitions table:

Column	Type	Description
id	UUID	Primary key (auto-generated)
org_id	UUID	References organizations.id (nullable)
partner_id	UUID	References partners.id (nullable)
name	VARCHAR(100)	Human-readable field name
field_key	VARCHAR(100)	Machine-readable key
type	ENUM	One of text, number, boolean, dropdown, date
options	JSONB	Validation options (choices, min, max, pattern, placeholder)
required	BOOLEAN	Whether the field is required (default: false)
default_value	JSONB	Default value for the field
device_types	TEXT[]	Array of applicable OS types
created_at	TIMESTAMP	Creation timestamp
updated_at	TIMESTAMP	Last modification timestamp

Device values are stored in the custom_fields JSONB column on the devices table as a flat key-value object.

---

Troubleshooting

Field key rejected

The fieldKey must match the pattern ^[a-z][a-z0-9_]*$. It must start with a lowercase letter and contain only lowercase letters, digits, and underscores. Uppercase letters, hyphens, spaces, and leading digits are not allowed.

Invalid: Asset-Number, 3rd_floor, Department Name Valid: asset_number, third_floor, department_name

”Provide either orgId or partnerId, not both”

When creating a field definition, supply at most one of orgId or partnerId. A field is scoped to a single tenant level. If you are authenticated as an organisation user, you do not need to supply either — the API infers your organisation from the auth context.

Custom field values not appearing on device

Verify that the PATCH /api/v1/devices/:id request includes a customFields key in the JSON body, not custom_fields. The API expects camelCase property names. Also confirm that each value is a string, number, boolean, or null — objects and arrays are not accepted as values.

Deleted definition but values remain on devices

Deleting a field definition does not cascade to device values. The values in the custom_fields JSONB column on each device persist after the definition is removed. To clean up orphaned values, patch each affected device with the field key set to null.

”Custom field not found” on GET/PATCH/DELETE

The field ID must be a valid UUID for a definition that exists and is accessible to your auth scope. Organisation users cannot see or modify partner-scoped definitions. Partner users cannot see or modify definitions belonging to organisations outside their access.