How do I create, update, or delete custom field definitions via the External API?

Custom Field Definitions via the External API

Custom field definitions control the schema — the label, data type, and which entity types the field applies to. Managing definitions is separate from reading or writing field values on individual records (which use per-entity endpoints like .../sales-orders/{id}/custom-fields).

All definition endpoints live under:

/external/api/v1/custom-fields

List definitions

GET /external/api/v1/custom-fields

Returns all custom field definitions, sorted alphabetically by label.

Optional query parameter:

Parameter	Description
`object_type`	Filter to definitions linked to a specific entity type (e.g. `salesOrder`, `supplier`, `rfq`). Invalid values return `422`.

Supported object_type values: salesOrder, salesOrderItem, shipmentItem, rfq, assemblyOrder, disassemblyOrder, clientInvoice, businessAccount, supplier, supplierPurchaseOrder, supplierPurchaseOrderShipment, fulfillmentOrder, returnOrder, workOrder, deal, transferOrder, productionRun

Get a single definition

GET /external/api/v1/custom-fields/{id}

Returns one definition by its numeric ID.

Create a definition

POST /external/api/v1/custom-fields

Request body (JSON):

Field	Required	Notes
`label`	✅ Yes	Must be unique across all custom fields. Max 255 characters.
`type`	✅ Yes	One of: `number`, `date`, `string`, `dropdown`, `multi_dropdown`
`options`	Conditional	Required when `type` is `dropdown` or `multi_dropdown`. Must include at least one choice.
`options.choices`	Conditional	Array of choice strings for dropdown types.
`options.helpText`	No	Up to 500 characters.
`options.maxLength`	No	Integer ≥ 1.
`options.minLength`	No	Integer ≥ 0.
`category`	No	Optional grouping label. Max 255 characters.
`object_types`	No	Array of entity-type strings. Omitting it creates the field with no entity-type links.

Returns 201 Created with the new definition object.

Full update (replace)

PUT /external/api/v1/custom-fields/{id}

Same fields as create. Key differences from create:

object_types is required. Pass an empty array [] to remove all entity-type links.
All other fields follow the same rules as create.

Partial update

PATCH /external/api/v1/custom-fields/{id}

Send only the fields you want to change. Fields you omit are left unchanged.

You may send any subset of label, type, options, category, and object_types.
If you include object_types, an empty array [] removes all entity-type links.
If you change type to dropdown or multi_dropdown, you must also include options.

PATCH /external/api/v1/custom-fields/{id}/choices

Only works on dropdown and multi_dropdown fields. Lets you add or remove individual choices without replacing the full options object.

Request body:

Field	Required	Notes
`add`	Conditional	Array of choice strings to add. Duplicates are ignored.
`remove`	Conditional	Array of choice strings to remove.

At least one of add or remove must be provided and non-empty. Removing all choices returns 422 — a dropdown must always retain at least one choice.

Delete a definition

DELETE /external/api/v1/custom-fields/{id}

Response	Meaning
`204 No Content`	Successfully deleted.
`404 Not Found`	No definition with that ID exists.
`422 Unprocessable`	The field still has stored values on one or more records and cannot be deleted.

Response shape

All read and write endpoints return a definition object with these fields:

Field	Description
`id`	Numeric ID of the definition.
`label`	Display name.
`type`	`number`, `date`, `string`, `dropdown`, or `multi_dropdown`.
`options`	Options object (choices, helpText, etc.) — `null` for non-dropdown types.
`category`	Optional grouping label.
`object_types`	Array of entity-type strings this field is linked to.
`created_at`	ISO timestamp.
`updated_at`	ISO timestamp.

Definition vs. values — quick reminder

These endpoints only manage what fields exist and their configuration. To read or write actual field values on a specific order, product, supplier, etc., use the record-level custom-fields routes (for example GET /external/api/v1/sales-orders/{id}/custom-fields).