Creating a Load Type Form

This guide explains how to create custom forms tied to specific load types and collect structured data during the appointment booking process via the Opendock API. Our web applications leverage this feature to gather critical information about appointments, enabling better operational visibility and data management.

1. Create a Load Type Form

Create a form and associate it with one or more load types from a warehouse.

API Endpoint:

POST /warehouses/{warehouseId}/custom-forms

📚 API Docs

Example Request:

{
  "loadTypeIds": [
    "a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5"
  ],
  "formName": "Load Type Form"
}

🧾 Notes:

• This will create three forms (one for each Opendock application).
  • All: Visible to all requests (including API integrations)
  • Warehouse: Visible/required only through the Warehouse Management UI
  • Carrier: Visible/required only through the Scheduling Portal UI
• You can retrieve them using:
  • GET /custom-forms/form
• For each loadtype a Trigger entity will be created pointing to these forms, which represents when the form needs to be rendered by the UI. For API integrations, the trigger.app = all is what matters.
  • GET /custom-forms/trigger

---

2. Create Global Fields

Define reusable fields for your form, such as Seal Number or Temperature. These fields can be used for any custom form within your Organization.

API Endpoint:

POST /custom-forms/field

📚 API Docs

Example Request:

{
  "label": "Temperature",
  "type": "str",
  "description": "Enter the trailer temperature",
  "placeholder": "60F"
}

🧾 Notes:

• For type reference, please refer to the custom fields types overview
• Repeat this for each field you need. These global fields can be reused across multiple forms.
• Fetch existing fields GET /custom-forms/field for reference, adding a field may not be needed.

---

3. Attach Fields to the Forms (Form Field Entity)

Link the global fields to the specific form. Be mindful: each Opendock app will have a form with the same name but a different purpose.

These forms are linked to the Trigger entity, which defines the app context (All, Warehouse, Carrier).

API Endpoint:

POST /custom-forms/form-field

📚 API Docs

Example Request:

{
  "order": 1,
  "formId": "string",
  "fieldId": "string",
  "required": true,
  "overrideLabel": "Last Name"
}

🧾 Notes:

• You can retrieve a list of available fields using GET /custom-forms/fields
• When required, the appointment creation will fail if such field is not present at the payload, inside the customFormsData field.

---

4. Book an Appointment (with Custom Forms Data)

Send form data when creating an appointment using the customFormsData field.

API Endpoint:

POST /appointment

Example Request:

{
  "customFormsData": [
    {
      "value": "John Doe",
      "formFieldId": "a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5",
      "triggerId": "a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5"
    },
    // ... other fields
  ]
}

📚 API Docs Form Data endpoint

Retrieve Form Data:

GET /custom-forms/form-data?s={"objectId":"<appointment_id>"}

Update Form Data:

PATCH /custom-forms/form-data/{form-data-id}

Notes:

• The form definition is linked to the load type selected during appointment creation.
• The customFormsData property must be provided when booking an appointment.
• This ensures the data is stored in a separate entity, making it easy to search and manage.