Adding Custom Columns to the Item Master

This guide walks through the full lifecycle of extending the Item Master with custom fields - defining the columns, writing values when creating or updating items, and reading them back in list and detail responses.

A common use case: your organisation tracks an internal product classification code and a hazmat flag that don't exist in Knosc's built-in item fields. This guide uses those two fields as the running example.

---

Prerequisites

Requirement	Detail
Auth	Active session cookie + CSRF token (see Authentication)
Privilege - read custom columns	Custom Columns / View
Privilege - create/edit custom columns	Custom Columns / Edit
Privilege - read items	Item Master / View
Privilege - create/edit items	Item Master / Edit

---

Step 1 - Check Existing Custom Columns

Before creating new columns, confirm what is already defined for ItemMaster to avoid duplicate keys.

curl -b cookies.txt \
  "https://acme.knosc.com/api/custom-columns/ItemMaster"

Response:

{
  "data": []
}

An empty array means no custom columns are defined yet for this table.

---

Step 2 - Create Custom Columns

2a. String column - Product Classification Code

curl -b cookies.txt -X POST \
  "https://acme.knosc.com/api/custom-columns" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: <csrf>" \
  -d '{
    "table": "ItemMaster",
    "key": "Product Classification Code",
    "format": "string",
    "alias": "Classification",
    "required": false,
    "default_value": null
  }'

Response:

{
  "data": {
    "id": 101,
    "table": "ItemMaster",
    "key": "Product Classification Code",
    "format": "string",
    "alias": "Classification",
    "required": false,
    "default_value": null
  }
}

Note the returned id - you'll need it if you update or delete this column later.

2b. Boolean column - Hazmat Flag

curl -b cookies.txt -X POST \
  "https://acme.knosc.com/api/custom-columns" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: <csrf>" \
  -d '{
    "table": "ItemMaster",
    "key": "Hazmat",
    "format": "boolean",
    "alias": "Hazardous Material",
    "required": false,
    "default_value": false
  }'

Response:

{
  "data": {
    "id": 102,
    "table": "ItemMaster",
    "key": "Hazmat",
    "format": "boolean",
    "alias": "Hazardous Material",
    "required": false,
    "default_value": false
  }
}

---

Step 3 - Create an Item with Custom Column Values

Custom column values are passed in the same request body as built-in fields. Use the key exactly as defined.

curl -b cookies.txt -X POST \
  "https://acme.knosc.com/api/item-master" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: <csrf>" \
  -d '{
    "Item Number": "CHEM-4471",
    "Item Description": "Solvent Cleaner - Industrial",
    "Item Type": "Raw Material",
    "Item Unit": "LTR",
    "Item Status": "Active",
    "Product Classification Code": "HPC-SOLV",
    "Hazmat": true
  }'

Response:

{
  "data": {
    "id": 310,
    "Item Number": "CHEM-4471",
    "Item Description": "Solvent Cleaner - Industrial",
    "Item Type": "Raw Material",
    "Item Unit": "LTR",
    "Item Status": "Active",
    "Product Classification Code": "HPC-SOLV",
    "Hazmat": true
  }
}

The custom fields are returned alongside the built-in fields in the response.

---

Step 4 - Update Custom Column Values on an Existing Item

To set or change custom column values on an item that already exists, use PUT with only the fields you want to change.

curl -b cookies.txt -X PUT \
  "https://acme.knosc.com/api/item-master/310" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: <csrf>" \
  -d '{
    "Product Classification Code": "HPC-SOLV-II",
    "Hazmat": true
  }'

Unchanged fields (built-in or custom) are not affected.

---

Step 5 - Read Custom Columns Back

Single item

curl -b cookies.txt "https://acme.knosc.com/api/item-master/310"

{
  "data": {
    "id": 310,
    "Item Number": "CHEM-4471",
    "Item Description": "Solvent Cleaner - Industrial",
    "Item Type": "Raw Material",
    "Item Unit": "LTR",
    "Item Status": "Active",
    "Product Classification Code": "HPC-SOLV-II",
    "Hazmat": true
  }
}

List - custom columns appear in headers and rows

curl -b cookies.txt "https://acme.knosc.com/api/item-master"

{
  "data": {
    "headers": [
      { "key": "Item Number",                 "format": "string",  "alias": "Item Number" },
      { "key": "Item Description",            "format": "string",  "alias": "Description" },
      { "key": "Item Status",                 "format": "string",  "alias": "Status" },
      { "key": "Product Classification Code", "format": "string",  "alias": "Classification" },
      { "key": "Hazmat",                      "format": "boolean", "alias": "Hazardous Material" }
    ],
    "rows": [
      {
        "id": 55,
        "Item Number": "ITEM-A",
        "Item Description": "Widget Assembly - Type A",
        "Item Status": "Active",
        "Product Classification Code": null,
        "Hazmat": false
      },
      {
        "id": 310,
        "Item Number": "CHEM-4471",
        "Item Description": "Solvent Cleaner - Industrial",
        "Item Status": "Active",
        "Product Classification Code": "HPC-SOLV-II",
        "Hazmat": true
      }
    ]
  },
  "extra": {
    "page": 1,
    "page_size": 50,
    "total": 2,
    "total_pages": 1
  }
}

Items without a value for the custom column return null (or the default_value if one was set).

---

Step 6 - Filter by a Custom Column (Optional)

Custom columns are filterable like any other column. Use the key as the filter parameter:

curl -b cookies.txt \
  "https://acme.knosc.com/api/item-master?filter[Hazmat]=true"

curl -b cookies.txt \
  "https://acme.knosc.com/api/item-master?filter[Product+Classification+Code]=HPC-SOLV-II"

---

Full Python Workflow

import requests

BASE_URL = "https://acme.knosc.com/api"

# Assumes session is already authenticated (see Quick Start guide)
session = requests.Session()
session.headers.update({"X-XSRF-TOKEN": "<csrf>"})

# 1. Create custom columns
session.post(f"{BASE_URL}/custom-columns", json={
    "table": "ItemMaster",
    "key": "Product Classification Code",
    "format": "string",
    "alias": "Classification",
    "required": False,
})

session.post(f"{BASE_URL}/custom-columns", json={
    "table": "ItemMaster",
    "key": "Hazmat",
    "format": "boolean",
    "alias": "Hazardous Material",
    "required": False,
    "default_value": False,
})

# 2. Create an item with custom values
response = session.post(f"{BASE_URL}/item-master", json={
    "Item Number": "CHEM-4471",
    "Item Description": "Solvent Cleaner - Industrial",
    "Item Type": "Raw Material",
    "Item Unit": "LTR",
    "Item Status": "Active",
    "Product Classification Code": "HPC-SOLV",
    "Hazmat": True,
})
item_id = response.json()["data"]["id"]

# 3. Fetch all hazmat items
response = session.get(f"{BASE_URL}/item-master", params={"filter[Hazmat]": "true"})
hazmat_items = response.json()["data"]["rows"]
print(f"Found {len(hazmat_items)} hazmat items")

# 4. Update classification on an existing item
session.put(f"{BASE_URL}/item-master/{item_id}", json={
    "Product Classification Code": "HPC-SOLV-II",
})

---

Managing Columns Over Time

Rename the display label (alias)

The key used in API responses never changes - only the display label (alias) can be updated freely.

curl -b cookies.txt -X PUT \
  "https://acme.knosc.com/api/custom-columns/101" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: <csrf>" \
  -d '{"alias": "Classification Code"}'

Delete a custom column

curl -b cookies.txt -X DELETE \
  "https://acme.knosc.com/api/custom-columns/101" \
  -H "X-XSRF-TOKEN: <csrf>"

Warning: Deleting a custom column permanently removes all stored values for that column across every item record. This action cannot be undone.

---

Supported Column Formats

Format	JSON type	Example value
string	string	"HPC-SOLV"
number	number	42.5
boolean	boolean	true
date	string (ISO 8601)	"2024-06-01"
currency	number	19.99

---

Related

• Custom Columns Reference
• Item Master Reference
• Custom Columns Guide
• Filtering & Sorting