---
title: "Update a custom field"
method: POST
path: "/public/v1/custom-fields/{id}"
tags: ["CustomField"]
---

# Update a custom field

`POST /public/v1/custom-fields/{id}`

Update an existing custom field. Only `name`, `description`, `required`, and `field_options` are editable here; `field_type`, `parent_object`, and `filterable` are fixed at creation. This endpoint does not accept those three fields — any value sent for them is silently ignored, not applied.

Each body field is sparse: omit a field to leave it unchanged. For `name`, `description`, and `required`, sending an explicit null is treated the same as omitting it — the field keeps its current value, so an existing `description` cannot be blanked back to empty through this endpoint. Only the fields you send with a real value are applied, so a request that sends just `name` renames the field and leaves its options and settings intact.

`field_options` is a full replacement of the option list, and editing it ripples through the whole company's data:
• An option present before but absent from the new list is deleted. Deleting an option scrubs that value out of every record of this entity type — for a `dropdown` the record's selection is cleared, for a `checkbox` that one value is removed from the record's selected set — and removes it from any saved filters that referenced it (a filter left with no values is dropped). This runs across all matching records for the company and can be a large change.
• An option that stays in the list is preserved along with the records that selected it.
• A new value in the list is added as a selectable option.
• Renaming an option (by editing its text while keeping its position) carries the new name into every record and saved filter that used the old value.
Omitting `field_options` entirely leaves the current options untouched. This field applies only to `dropdown` and `checkbox` fields.

This is a settings/metadata change only — it does not affect inventory, Metrc, or BioTrack. Returns 404 when no field with that id belongs to the company.

Required permission: `settings_permissions_custom_fields`.

## Path parameters

- `id` integer, required

## Request body

- object
  - `name` string — New display name. Omit (or send null) to leave unchanged. Must stay unique among the fields on the same entity type for this company; uniqueness is case-insensitive, so `Lab` and `lab` collide. At most 70 characters, not a reserved name, and free of certain special characters. Renaming also updates the field's column label in the Distru app.
  - `description` string — New description. Omit (or send null) to leave unchanged — null does not clear an existing description. At most 100 characters.
  - `required` boolean — New value for whether a value must be supplied when a record is saved. Omit to leave unchanged.
  - `field_options` string[] — The complete new option list for a `dropdown` or `checkbox` field, e.g. `["Lab A", "Lab C"]`. This is a full replace, not a merge: any current option missing from this list is deleted and scrubbed from every record and saved filter that used it (see the endpoint description). Each value must be unique, non-empty, at most 255 characters, and contain no commas. Omit the field to leave the current options unchanged; send the complete list to change them. Do not send null. Ignored for `text` and `date` fields.
  - `disabled_field_options` string[] — The complete new set of turned-off options for a `dropdown` or `checkbox` field. This is a full replace: an option listed here is disabled, and any option not listed is re-enabled. A disabled option can no longer be selected on new or edited records but stays in `field_options` so records already holding it keep displaying it. Every value must be one of the field's options (the new `field_options` when you also send that, otherwise the current ones); an unknown value is rejected. Omit to leave the current disabled set unchanged; send `[]` to re-enable everything. Ignored for `text` and `date` fields.

## Response `200`

Custom field updated

## Other responses

- `400` — Invalid parameters
- `401` — Missing or invalid API token
- `403` — The API token lacks the required permission
- `404` — Not Found

---

[API](https://skmtc.dev/distru/apis/distru-api.md) · [All operations](https://skmtc.dev/distru/apis/distru-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/distru/distru-api/revisions/f8930b2c2924/schema)