Custom Fields Companies People Design

🧩 Custom fields on companies and people - design (#279)

The last part of #279. Parts 1, 2 and 4 - outside reference, tax ID, the companies API, employee_id on users - shipped in 5.3.0 (REST API - Companies). Related: Custom ticket fields · Typed fields engine - Developer Guide · Companies - Developer Guide.

---

The shape

• Companies and people get custom fields, on the same engine as ticket custom fields: the same field types (text, number, date, yes/no, dropdown, link, email), the same way of laying them out in the form.
• Defined by administrators, under System.
• Values are read and written through the REST API as custom_fields, keyed by each field's key - so an ERP or CRM can keep them in step.
• Every change is recorded in history. Companies and people keep no history of their own today, so this adds one for these values.
• Directory sync never touches custom fields. People cannot edit their own custom fields on the portal.

Decisions

Put to Ed on 15 November 2026. His answers are what is built.

Question	Decision	Why
One list of fields for everyone, or per company too?	People: shared fields plus a company's own. Companies: one shared list.	A people field can be one client's need (Badge number). A company field describes companies, so a field "belonging to" one company would only ever appear on that company's own record - a note, not a field
Ed's first instinct was "both per company"	Talked through first; the downsides decided it	Per-company company fields add a scope setting, a field hidden on every other company and a column empty everywhere else, for almost no use. They can be added later without changing anything existing

Status

Built for 5.4.0 (changelog #2957-#2958): System → Custom fields, the Companies dialog, the person editor, the REST API and the API reference. User guide: Custom fields on companies and people. Developer guide: Custom fields - Developer Guide.

Downsides considered (per-company people fields)

Downside	Handled by
A person moves company, and the old company's field no longer applies	The value is kept but hidden, and comes back if they move back - as ticket custom fields do
Under All companies, a field only one company has makes a patchy column	Shared fields are the ones to use across companies
Two companies make fields with the same name meaning different things	Each has its own key; the settings list says which company a field belongs to
Thousands of companies make the settings list long	Each field shows its company in the list; a company filter is for later, with the company picker (#358)