Custom Field Definitions API

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

The integration API exposes the definition layer: creating, listing, editing, and deleting field definitions for the whole organization. The actual per-instance values (a specific gate code on a specific location, etc.) are managed through other parts of the platform.

These endpoints do not have an interactive Swagger explorer yet (the OpenAPI spec is not bundled in the Knowledge Hub), so all examples below are shown inline.

Definitions vs. instances — definitions are the schema; instances are the data. This API is the schema side only.

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.