Custom Field Definitions API

Open in Postman

Create, list, edit, and delete organization-wide custom field definitions in the Zendera transportation management system.

Custom fields let you record organization-specific data — gate codes, dock numbers, special handling instructions, compliance checkboxes — beyond Zendera’s built-in schema.

Where this fits in your operation

Custom fields are how operation-specific data your drivers and dispatchers need gets a structured home in Zendera:

Define a gate code field for delivery locations so drivers see it on every stop there.
Define an acknowledgment checkbox (“keys returned”, “temperature checked”) that drivers must confirm at the location.
Your system defines the fields once via this API; the values then live on locations and order locations.

Definitions vs. instances — definitions are the schema; instances are the data. This page covers the schema side; for setting values on locations and order locations (and tracking driver acknowledgments), see Custom Field Values.

Interactive API Explorer

Loading API Documentation...

List custom field definitions


GET /v1/admin/custom-field-definitions

Query parameters

Parameter	Notes
`isActive`	Optional boolean. Omit to get all definitions (active and inactive).

Response


{
  "definitions": [
    {
      "id": 42,
      "externalId": "gate_code",
      "label": "Gate code",
      "title": "Gate access code",
      "description": "Numeric code for the side gate",
      "icon": "lock",
      "colorScheme": { "background": "#FFE082", "text": "#000000" },
      "sortOrderBatch": "load",
      "displayOn": "delivery",
      "displayStyle": "badge",
      "isActive": true,
      "createdAt": "2025-08-01T10:00:00Z",
      "updatedAt": "2026-04-12T08:30:00Z"
    }
  ]
}

Create a custom field definition


POST /v1/admin/custom-field-definitions

Request body


{
  "externalId": "gate_code",
  "label": "Gate code",
  "title": "Gate access code",
  "description": "Numeric code for the side gate",
  "icon": "lock",
  "colorScheme": { "background": "#FFE082", "text": "#000000" },
  "sortOrderBatch": "load",
  "displayOn": "delivery",
  "displayStyle": "badge"
}

Field	Notes
`externalId`	Stable identifier you control. Used to reference the definition from imports.
`label`	Short label shown in the UI.
`title`	Longer descriptive title.
`description`	Optional long-form description.
`icon`	Icon name (UI affordance).
`colorScheme`	`{ background, text }` hex colours.
`sortOrderBatch`	Where the field sorts within batched displays: `char` (character / alphabetic), `load`, `drive`, or `num`.
`displayOn`	Which stop the field shows on: `current` (the stop where the value is set), `opposite` (the other stop on the order), `both`, `pickup`, or `delivery`.
`displayStyle`	How the field renders: `badge`, `card`, `registration`, or `popup`.

Response: the new CustomFieldDefinition with its assigned id, createdAt, updatedAt, and isActive: true.

Update a custom field definition


PUT /v1/admin/custom-field-definitions/{id}

Send only the fields you want to change. Any of the fields above can be edited (including externalId, isActive, and visual properties).

Request body


{
  "label": "Gate access code",
  "displayStyle": "card",
  "isActive": true
}

Response: the updated CustomFieldDefinition.

Delete (or deactivate) a custom field definition


DELETE /v1/admin/custom-field-definitions/{id}

Response


{
  "wasInactivated": true,
  "message": "Definition is in use; was inactivated rather than deleted"
}

Behaviour

If the definition has never been used, it’s hard-deleted. wasInactivated: false.
If the definition has been used (any historical instance value exists), it’s inactivated instead — preserving history. wasInactivated: true.

To reactivate, use the PUT endpoint with isActive: true.

Common gotchas

externalId is the stable identifier. Use a snake_case-style key like gate_code and treat it as effectively immutable; downstream integrations may key off it.
Display options affect the driver UI. displayOn, displayStyle, and sortOrderBatch change what the driver sees on their mobile app — review them with your operational team before changing.
Per-instance values are not in this API. Setting a gate code on a specific location, or recording a custom-field value at a specific stop, happens via the admin UI or via other integration touchpoints (e.g., customFields in the order import body).

What’s next

To set values on imported orders, use the customFields array within the order body in Importing and recurring orders.
For visualising what each definition looks like in the driver app, ask your Zendera admin to show you the mobile preview.