---
title: "Create a custom field"
method: POST
path: "/public/v1/custom-fields"
tags: ["CustomField"]
---

# Create a custom field

`POST /public/v1/custom-fields`

Create a new custom field on one entity type (`parent_object`).

Once created, the field is immediately available on every record of that entity type. Callers then set a per-record value by putting `"<id>": <value>` into that record's `custom_data` map on its own create/update endpoint, where `<id>` is the numeric id returned here. Creating a field does not touch existing records — they simply carry no value for it until one is written — and has no effect on inventory, Metrc, or BioTrack.

This endpoint only creates. It never updates: there is no upsert here, and `field_type`, `parent_object`, and `filterable` are fixed at creation and cannot be changed afterward. To edit a field's `name`, `description`, `required` flag, or option list later, use `POST /public/v1/custom-fields/{id}`.

Field-type rules the request must satisfy:
• `dropdown` and `checkbox` fields require a non-empty `field_options` list (the selectable values); each option must be unique, non-empty, and free of commas.
• `text` and `date` fields must not carry `field_options`, and are always non-filterable regardless of what `filterable` is sent.

Required permission: `settings_permissions_custom_fields`.

## Request body

- object
  - `name` string, required — Display name of the field, e.g. `Lab Name`. Required. Must be unique among the fields on the same `parent_object` for this company; uniqueness is case-insensitive, so `Lab` and `lab` collide. At most 70 characters. May not use a reserved name (such as `category`, `strain`, or `owner_id`) or contain certain special characters.
  - `description` string — Optional free-text note describing the field's purpose. At most 100 characters. Omit or send null for no description.
  - `parent_object` string, required — The entity type this field is attached to. Required and immutable after creation. One of: `assembly`, `batch`, `company`, `contact`, `invoice`, `order`, `package`, `product`, `purchase`, `request`, `return`, `shipment`, `stock_transfer`, `task`.
  - `field_type` 'checkbox' | 'date' | 'dropdown' | 'text', required — The kind of value this field stores. Required and immutable after creation. One of: `text` (free text), `date` (a calendar date), `dropdown` (a single choice from `field_options`), `checkbox` (one or more choices from `field_options`). `dropdown` and `checkbox` require `field_options`; `text` and `date` must not have them.
  - `filterable` boolean — Whether records of this entity type can be filtered by this field's value. Defaults to false when omitted. Applies only to `dropdown` and `checkbox` fields; for `text` and `date` it is forced to false no matter what is sent. Immutable after creation, so this is the only chance to enable it.
  - `required` boolean — Whether a value for this field must be supplied when a record of this entity type is saved in the Distru app. Defaults to false when omitted. Editable later via the update endpoint.
  - `field_options` string[] — The selectable values for `dropdown` and `checkbox` fields, e.g. `["Lab A", "Lab B"]`. Required and non-empty for those two types; each value must be unique, non-empty, at most 255 characters, and contain no commas. Must be omitted (or empty) for `text` and `date` fields.
  - `disabled_field_options` string[] — The subset of `field_options` to turn off. A disabled option can no longer be selected on new or edited records, but it stays in `field_options` so records already holding the value keep displaying it. Every value must also be present in `field_options`. Applies only to `dropdown` and `checkbox` fields; must be omitted (or empty) for `text` and `date`. Defaults to empty when omitted.

## Response `201`

Custom field created

## Other responses

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

---

[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)