Custom Fields Companies People

🧩 Custom fields on companies and people

5.4.0 · #279 · Developer guide: Custom fields on companies and people - Developer Guide · Design and decisions: Custom fields on companies and people - design · Related: Custom ticket fields · REST API - Companies

The details you keep about a client company or a person that FreeITSM has no field for - an account manager, a support tier, a contract renewal month, a badge number - as real fields, filled in on the record and kept in step from your ERP or CRM through the REST API.

---

Making the fields

System → Custom fields (administrators) has two tabs:

Tab	What
Companies	One list of fields for every company
People	Fields every company shares, or one company's own - so one client can have a Badge number the others never see. Which company a people field belongs to is chosen when it is made

Add makes a field: its name, its kind, an optional help text, and whether it is Required. The arrows set the order the fields are shown in. Delete takes a field away; its answers are kept out of sight, not thrown away.

Kind	Notes
Text	One line, or Several lines
Number	Decimal places and a unit (hours, users) if you like
Date	A date, a date and time, or a time
Yes / no	With Not set too, so an unanswered field is never read as No
Dropdown	One of the choices you list, one per line
Web address, Email address	Checked that they are one

A field's kind is fixed once it has answers; its name, help text, choices and Required can still change. Each field has a key (shown under its name), made from the name when the field is made and never changed - the REST API uses it.

Filling them in

• A company's - in System → Companies, in the company's dialog under Tax ID.
• A person's - in the person's details, in Tickets → Users or Assets → People, under Location. Changing the person's Company there brings up that company's fields.

A Required field must be filled in when a company or person is added, and cannot be cleared afterwards. Every change is recorded in the company's or the person's history.

A person who moves to another company stops showing the old company's own fields; their answers are kept, and come back if they move back. A directory - Active Directory, Entra, an address book - never changes custom fields, and people cannot change their own on the portal.

The REST API

/companies and /users return custom_fields - every field's key with its answer, or null - on the list, a single record, and after a create or change. Send the same object to create, change or upsert a company, or create or change a person:

POST /companies/upsert
{
  "external_ref": "CUST-00042",
  "name": "Acme Plumbing Ltd",
  "custom_fields": { "support_tier": "Gold", "account_manager": "Sarah Jones" }
}

An unknown key, or a value the field does not accept, is refused with 422 and nothing is saved. See REST API - Companies.

Upgrading

Run System → Database Verification after updating: it adds the seven tables these use. Nothing changes until an administrator makes a field.