Skip to main content

Custom Fields

Opendock facilities can require additional information when scheduling an appointment. This information is called custom fields. Warehouse users and carriers can provide this information when scheduling an appointment. The required schema is defined per warehouse, and can be retrieved using the customApptFieldsTemplate property.

warning

Once an appointment is created with a set of custom fields, these fields are stamped into that appointment and, no matter how the custom fields definition change in the future, the appointment will always have the custom fields that were defined once the appointment was created.

Custom Fields Properties​

Custom fields are defined by the following properties:

  • name, the unique identifier of the field (please see the note below)
  • type, the type of the field (see options below)
  • label, the human-readable name of the field
  • description (optional), a hint on how to use the field
  • placeholder (optional), a placeholder text for the field, only applicable for str and bigstr types
  • order, the order in which the field should be displayed
  • required (deprecated), whether the field is required or not for warehouse users
  • requiredForWarehouse, whether the field is required or not for warehouse users
  • requiredForCarrier, whether the field is required or not for carrier users
  • hiddenFromCarrier, whether the field should be hidden from carrier users, cannot be set to true if requiredForCarrier is true
  • minLengthOrValue (optional), the minimum length of the field or the minimum value of the field, only applicable for str and int types
  • maxLengthOrValue (optional), the maximum length of the field or the maximum value of the field, only applicable for str and int types
  • dropDownValues (optional), the options for the dropdown, only applicable for dropdown and dropdownmultiselect types
  • value (not applicable for the schema definition), the effective value of the field, whose data type depends on the field type

These properties compound JSON objects within the customApptFieldsTemplate array, within the Warehouse object. As mentioned above, these properties are copied over each individually created appointment, under the customFields property, and remain the same throughout the appointment's lifecycle.

note

You don't have to inform the name of the custom field, as this is going to be calculated upon creation as a combination of "type" and "label".

For example, if you have a custom field with the label "BOL" and type "doc", the name will be calculated as "docBOL".

Keep in mind, though, that the name will never change, even if you change the label or type of the field, which might be confusing. If you are concerned about that, a better approach would be deleting the custom field and creating a new one with the desired properties.

Custom Fields Types​

Opendock supports the following custom field types:

  • String = str
  • BigString = bigstr
  • Date = date
  • Bool = bool
  • Document = doc
  • MultiDocument = multidoc
  • Number = int
  • Email = email
  • Phone = phone
  • DropDown = dropdown
  • DropDownMultiSelect = dropdownmultiselect
  • ComboBox = combobox
  • Timestamp = timestamp

String​

The simplest one, a single line text input, for example, a license plate.

BigString​

A multi-line text input, for example, a description of the cargo.

Date​

A date input, for example, the expiry date of a perishable product. The format is YYYY-MM-DD (e.g. 2024-08-30).

Bool​

A boolean input (true or false), for example, whether the cargo is hazardous or not.

Document​

A single document upload, for example, a photo of the cargo. This value should be provided as a String, containing the key of the file, previously uploaded using the /storage endpoint. For example, when uploading a document, the storage endpoint will return a file key of storage/867cef72-a49d-42f1-a605-f49c5fbc7ae4/f59f6119ff/file.png. In order to download this file, prepend the key with the storage URL (https://files.opendock.com/), resulting in https://files.opendock.com/storage/867cef72-a49d-42f1-a605-f49c5fbc7ae4/f59f6119ff/file.png.

MultiDocument​

Same as above, but multiple. The files should be provided as an array of Strings, containing the keys of the files.

Number​

A number input, for example, the weight of the cargo. The value should be provided as an integer.

Email​

An email string, for example, the email of the person responsible for the cargo.

Phone​

A phone number string, for example, the phone number of the person responsible for the cargo. If the number omits the country code, it will be assumed to be an American number (+1), otherwise, please provide the full number, avoiding spaces, dashes, and parentheses, for example, +5511999999999.

Similar to a String, but instead of a free text input, the user must select one of the options predefined by the Warehouse. When defining the custom field, the dropDownValues property must be provided as an array of strings. Each dropdown supports up to 500 options.

Same as above, but multiple. The user can select multiple options. The value should be provided as an array of strings.

ComboBox​

Same as the DropDown, but the user can either select one of the predefined options or type an arbitrary value.

Timestamp​

A timestamp input, for example, the departure time of the cargo. The format is ISO-8601 with a timezone, for example, 2024-09-03T17:00:00.000Z, which means September 3rd, 2024, at 17:00 UTC.

tip

We recommend you use some library to handle dates and times, as the ISO-8601 format can be tricky to handle manually. Some suggestions would be: Luxon (JavaScript), java.time (Java), datetime (Python), DateTime (C#).

Examples​

Defining the custom fields schema​

In order to define the schema, you must provide the customApptFieldsTemplate property within the Warehouse object, through a PATCH request to the /warehouse/{id} endpoint.

{
   "customApptFieldsTemplate":[
      {
         "name":"docBOL",
         "type":"doc",
         "label":"BOL",
         "dropDownValues":[],
         "hiddenFromCarrier":false,
         "requiredForCarrier":false,
         "requiredForWarehouse":false
      },
      {
         "name":"dropdownExcellence Level",
         "type":"dropdown",
         "label":"Excellence Level",
         "dropDownValues":[
            "🥇 Gold",
            "🥈 Silver",
            "🥉 Bronze"
         ],
         "hiddenFromCarrier":false,
         "requiredForCarrier":true,
         "requiredForWarehouse":true
      },
      {
         "dropDownValues":[],
         "type":"email",
         "label":"Dispatcher",
         "placeholder":"xpto@example.com",
         "description":"Dispatcher's email address"
      }
   ]
}

Providing the fields when creating an appointment​

When it comes to create an appointment, you will inform the customFields object within the request body, along with the other appointment properties. Remember you have to re-inform the schema, not only the values, as this is going to be stamped into the appointment and remain static throughout its lifecycle.

{
   "customFields":[
      {
         "name":"docBOL",
         "type":"doc",
         "label":"BOL",
         "dropDownValues":[],
         "hiddenFromCarrier":false,
         "requiredForCarrier":false,
         "requiredForWarehouse":false,
         "required":false,
         "value":"storage/867cef72-a49d-42f1-a605-f49c5fbc7ae4/86bc2d0508/bol.png"
      },
      {
         "name":"dropdownExcellence Level",
         "type":"dropdown",
         "label":"Excellence Level",
         "dropDownValues":[
            "🥇 Gold",
            "🥈 Silver",
            "🥉 Bronze"
         ],
         "hiddenFromCarrier":false,
         "requiredForCarrier":true,
         "requiredForWarehouse":true,
         "required":true,
         "value":"🥇 Gold"
      },
      {
         "name":"emailDispatcher",
         "type":"email",
         "label":"Dispatcher",
         "description":"Dispatcher's email address",
         "placeholder":"xpto@example.com",
         "dropDownValues":[],
         "hiddenFromCarrier":false,
         "requiredForCarrier":false,
         "requiredForWarehouse":false,
         "required":false,
         "value":"luiz@opendock.com"
      }
   ]
}

Querying Custom Fields​

When listing or searching appointments, the custom fields are returned as part of the appointment object. Our API currently does not support querying appointments based on custom fields values. If you don't need the custom fields values when listing appointments, though, you can use the fields query parameter to exclude them from the response.

Examples:

  • GET /appointments?fields=id,start,end,confirmationNumber,customFields (returns the custom fields)
  • GET /appointments?fields=id,start,end,confirmationNumber (does not return the custom fields)