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

Last updated: September 25, 2026

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.


Manage dropdown choices incrementally

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