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.
BearerAuthorizationBearer <token>API token generated in Distru (Settings → Distru API). Send it on every request as Authorization: Bearer YOUR_API_TOKEN.
application/json- body
name*stringDisplay 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?stringOptional free-text note describing the field's purpose. At most 100 characters. Omit or send null for no description.
parent_object*stringThe 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*stringThe 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.
"checkbox""date""dropdown""text"filterable?booleanWhether 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?booleanWhether 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?array<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?array<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.
Custom field created
*/*- response
A single custom field definition wrapped in a data envelope
data?A custom field definition
curl -X POST 'https://app.distru.com/public/v1/custom-fields' \ -H 'Content-Type: application/json' \ -d '{ "field_options": [ "A", "B" ], "field_type": "dropdown", "filterable": true, "name": "Dropdown Field", "parent_object": "product"}'{ "data": { "description": null, "disabled_field_options": [], "field_options": [ "A", "B" ], "field_type": "dropdown", "filterable": true, "id": 54, "name": "Dropdown Field", "parent_object": "product", "required": false }}