Sign in
CustomField

Create a custom field

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.

post/public/v1/custom-fields

Request body

namestring 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.

descriptionstring

Optional free-text note describing the field's purpose. At most 100 characters. Omit or send null for no description.

parent_objectstring 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.

filterableboolean

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.

requiredboolean

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_optionsstring[]

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_optionsstring[]

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

Custom field created

Changes

No recorded changes to this endpoint across all 1 revision of this API.