AirTrail

Custom fields let you track structured data beyond what AirTrail provides out of the box. A field can apply to an entire flight or to each passenger on a flight. Definitions are configured globally by an admin.

Managing custom fields

To manage custom fields, go to Settings > Custom Fields. Choose Flight fields or Passenger fields, then create, edit, reorder, or delete definitions for that scope.

Each field definition has the following properties:

Key: A unique identifier used internally (lowercase letters, numbers, and underscores).
Label: The display name shown in the UI.
Type: The kind of data the field stores (see Field types below).
Required: Whether the field must be filled in before saving its flight or passenger.
Default value: An optional value that is pre-filled when the flight or passenger doesn't have a saved value for the field.

Field types

Type	Description	Stored value
Short text	Single-line text input	String
Long text	Multi-line textarea	String
Number	Numeric input	Number
Boolean	Toggle switch	`true` / `false`
Date	Date picker	Date string (YYYY-MM-DD)
Select	Dropdown from a list of options	String (selected option)
Multi-select	Select one or more listed options	Array of strings
Airport	Airport picker (same as the flight form)	Airport object
Airline	Airline picker	Airline object
Aircraft	Aircraft picker	Aircraft object

Using custom fields

When adding or editing a flight:

Click the sliders icon next to the Save button for flight fields.
Click the sliders icon beside an individual passenger for passenger fields.

Fields with default values are pre-filled automatically. Passenger values keep their identity when the flight is edited because passenger IDs remain stable.

Unsaved defaults

When editing an existing flight, if new custom fields have been added since the flight or passenger was created, the relevant modal shows an amber badge on the trigger button and a warning inside.

Some fields below are showing default values that haven't been saved on this flight yet. Saving the flight will apply these defaults.

This ensures you're aware that saving the flight will persist those default values.

Validation

Required fields are validated before the flight can be saved. If any required custom fields are empty, the modal opens automatically with per-field error messages.

Text fields support optional validation rules (min/max length, regex pattern). Number fields support min/max value constraints.

API usage

Custom fields are part of the flight save endpoint (POST /flight/save). Pass flight fields in the root customFields object and passenger fields inside each passenger. Both objects are keyed by field key:

{
  "from": "KJFK",
  "to": "EGLL",
  "departure": "2026-02-20",
  "passengers": [
    {
      "userId": "<USER_ID>",
      "flightReason": "business",
      "customFields": {
        "meal_preferences": ["Vegetarian", "Gluten-free"]
      }
    }
  ],
  "customFields": {
    "booking_reference": "ABC123",
    "delay_minutes": 15
  }
}

Required custom fields are enforced server-side for both create and update requests.

Export and import

Flight and passenger custom field values are included in the JSON export. Entity-type fields (airport, airline, aircraft) are expanded to their full objects, matching the format used for the flight's own airport and airline data.

Custom field values are exported for reference but are not restored when re-importing into AirTrail. The field definitions and their values would need to be recreated manually after an import.

Custom fields are not included in the CSV export.

Custom Fields