Purpose: Use this API to create a new dispatch.

📘

Custom Fields - Dispatches and Dispatch Stops

Dispatches and Dispatch Stops support custom fields from custom_field1 through custom_field100. You can use conditional logic to auto-populate these fields, and update the corresponding TMS data.

NOTE

• Dispatch custom fields are sent at the top level of the POST /v3/dispatches request.
• Dispatch stop custom fields are sent inside the relevant dispatch_stops[] - object.

Example

Sample Request

POST /v3/dispatches
{
  "custom_field7": "dispatch value",
  "dispatch_stops": [
    {
      "custom_field12": "stop value"
    }
  ]
}

Conditional Logic

When a dispatch form is submitted, the conditional logic will use the supported vehicle and dispatch-stop context values.

• Values written to dispatch or dispatch-stop custom fields are saved with the associated TMS data.
• Values entered by users in visible fields are preserved and are not overwritten by conditional logic.
• After synchronization, conditional logic can change which fields are displayed or required.

Supported Vehicle Context Keys

Conditional logic supports the vehicle.* expression syntax for evaluating vehicle context and auto-populating fields. The following vehicle context keys are currently supported:

Context key	Description
vehicle.vin	Vehicle identification number (VIN).
vehicle.odometer	Current odometer value, converted to the driver's preferred distance unit.
vehicle.fuel_level	Current primary fuel-level reading, when available and within the valid range.
vehicle.engine_hours	Current engine-hours reading, when available.
vehicle.location.city	Current vehicle location city.
vehicle.location.state_code_absolute	Current vehicle location state code.
vehicle.location.latitude	Current vehicle latitude.
vehicle.location.longitude	Current vehicle longitude.

These are conditional-form context keys and auto-population sources. They are not customer-supplied fields in the POST /v3/dispatches request.

vehicle.id is client-owned and is not auto-populated by the backend. Other vehicle paths are not currently resolved for conditional logic.

Dispatch-stop Timing Fields

Dispatch-stop timing fields represent either the actual time a vehicle arrived at or departed from a stop, or the scheduled appointment window for the stop.

Field	Description
dispatch_stop.arrive_time	The actual arrival timestamp for the stop, based on the timestamp submitted through the arrive form.
dispatch_stop.depart_time	The actual departure timestamp for the stop, based on the timestamp submitted through the depart form.
dispatch_stop.early_date	The scheduled appointment-window start.
dispatch_stop.late_date	The scheduled appointment-window end.

arrive_time and depart_time represent actual arrival and departure times. early_date and late_date represent the scheduled appointment window and should not be used as substitutes for actual arrival or departure timestamps.

👍

Team Dispatches

We are introducing a Co-Driver association method, that allows multiple drivers to be "authorized" for a single dispatch trip. This enables seamless swapping of the "_Active Driver" role directly from the mobile app, ensuring the driver currently behind the wheel has full visibility without requiring manual dispatcher intervention or trip re-assignment.

Check the Sample Request Body section for info on the request parameters.

How to use it
In the sample request body, for the co_driversobject, do the following:

1. Mention the driver ID of the primary driver.
2. Mention the driver ID of the secondary driver.

For example, if your primary driver ID is 4713870, and co_driver ID is 4713860, you will specify the body as follows:

"dispatch_trips": [

{
"id": 31911,
"driver_id": 4713870,
"co_drivers": [
4713870,
4713860,
]

📘

NOTE

This endpoint will only accept a JSON Object as body parameters. Below is the format of the request body.

You may include more trips with multiple stops. Ensure that every trip has a unique stop.

Disclaimer: The following request body JSON is just an example and you must change the form IDs and the location IDs that correspond to your fleet for it to work.

Sample Request Body

{
  "vendor_id":"VV-1",
  "status":"planned",
  "dispatch_stops":[
    {
      "vendor_id":"VDS-1",
      "type":"pickup",
      "number":1,
      "early_date":"2023-03-13T19:13:00+00:00",
      "late_date":"2023-03-15T19:13:00+00:00",
      "form_ids":[
        "1ee148ac-6083-4b5a-af7b-75b875bb233f",
        "f60e5305-c2e2-45d7-97d7-eb4760b1a973"
      ],
      "vendor_dispatch_location_id":"VDSL-1",
      "status":"available"
    }
  ],
  "dispatch_trips":[
    {
      "vendor_id":"VT-1",
      "vehicle_id":64734,
      "driver_id":1088505,
      "vendor_stop_ids":[
        "VDS-1"
      ],
      "status":"not_started"
    }
  ]
}

{
  "vendor_id":"VV-2",
  "status":"planned",
  "dispatch_stops":[
    {
      "vendor_id":"VDS-1",
      "type":"pickup",
      "number":1,
      "early_date":"2023-03-13T19:13:00+00:00",
      "late_date":"2023-03-15T19:13:00+00:00",
      "form_ids":[
        "1ee148ac-6083-4b5a-af7b-75b875bb233f",
        "f60e5305-c2e2-45d7-97d7-eb4760b1a973"
      ],
      "vendor_dispatch_location_id":"VDSL-1",
      "status":"available"
    },
    {
      "vendor_id":"VDS-2",
      "type":"delivery",
      "number":2,
      "early_date":"2023-03-13T23:13:00+00:00",
      "late_date":"2023-03-15T23:13:00+00:00",
      "form_ids":[
        "1ee148ac-6083-4b5a-af7b-75b875bb233f",
        "f60e5305-c2e2-45d7-97d7-eb4760b1a973"
      ],
      "vendor_dispatch_location_id":"VDSL-2",
      "status":"available"
    }
  ],
  "dispatch_trips":[
    {
      "vendor_id":"VT-1",
      "vehicle_id":64734,
      "driver_id":1088505,
      "vendor_stop_ids":[
        "VDS-1",
        "VDS-2"
      ],
      "status":"not_started"
    }
  ]
}

{
  "vendor_id":"VV-3",
  "status":"planned",
  "dispatch_stops":[
    {
      "vendor_id":"VDS-1",
      "type":"pickup",
      "number":1,
      "early_date":"2023-03-13T19:13:00+00:00",
      "late_date":"2023-03-15T19:13:00+00:00",
      "form_ids":[
        "1ee148ac-6083-4b5a-af7b-75b875bb233f",
        "f60e5305-c2e2-45d7-97d7-eb4760b1a973"
      ],
      "vendor_dispatch_location_id":"VDSL-1",
      "status":"available"
    },
    {
      "vendor_id":"VDS-2",
      "type":"delivery",
      "number":2,
      "early_date":"2023-03-13T23:13:00+00:00",
      "late_date":"2023-03-15T23:13:00+00:00",
      "form_ids":[
        "1ee148ac-6083-4b5a-af7b-75b875bb233f",
        "f60e5305-c2e2-45d7-97d7-eb4760b1a973"
      ],
      "vendor_dispatch_location_id":"VDSL-2",
      "status":"available"
    }
  ],
  "dispatch_trips":[
    {
      "vendor_id":"VT-1",
      "vehicle_id":64734,
      "driver_id":1088505,
      "vendor_stop_ids":[
        "VDS-1"
      ],
      "status":"not_started"
    },
    {
      "vendor_id":"VT-2",
      "vehicle_id":64735,
      "driver_id":1088506,
      "vendor_stop_ids":[
        "VDS-2"
      ],
      "status":"not_started"
    }
  ]
}

{
  "dispatches": [
    {
      "id": 43686,
      "order_number": "574869",
      "status": "planned",
      "dispatch_team_driving_enabled_v3": true,
      "dispatch_trips": [
        {
          "id": 31911,
          "driver_id": 4713870,
          "co_drivers": [
            4713860,
            4713870,
          ],
          "vehicle_id": 1320960,
          "dispatch_stops": [
            {
              "dispatch_stop": {
                "id": 42,
                "vendor_id": "VDS-1",
                "bill_of_lading": null,
                "comments": null,
                "driver_load": false,
                "early_date": "2017-07-13T19:13:00+00:00",
                "form_ids": [
                  "0b90adf8-2321-4198-9315-5fb57e155c15",
                  "2a00385b-7de3-48b2-9bfc-842eb168e535",
                  "fff80dfb-dda9-4502-8ca6-6c69fa6d70d6"
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

Response Parameters

dispatch

• Type: Object
• Description: Details of a dispatch, including stops and trips associated with it.

id

• Type: Integer
• Description: The unique identifier for the dispatch.

additional_drops

• Type: String
• Description: Additional drop locations, if any.

additional_pickups

• Type: String
• Description: Additional pickup locations, if any.

loaded_miles

• Type: Integer
• Description: The loaded miles for the dispatch.

order_pieces

• Type: Integer
• Description: Number of order pieces.

order_volume

• Type: Integer
• Description: Volume of the order.

order_weight

• Type: Integer
• Description: Weight of the order.

product

• Type: String
• Description: Product details associated with the dispatch.

pickup_number

• Type: String
• Description: Pickup number associated with the dispatch.

status

• Type: String
• Description: The current status of the dispatch (e.g., "planned").

status_updated_at

• Type: String (DateTime)
• Description: The timestamp of the last status update.

temperature_max

• Type: Float
• Description: Maximum temperature for the dispatch, if applicable.

temperature_min

• Type: Float
• Description: Minimum temperature for the dispatch, if applicable.

trailer

• Type: String
• Description: Trailer information associated with the dispatch.

auto_complete_forms

• Type: Boolean
• Description: Indicates if forms are auto-completed.

consignee_refno

• Type: String
• Description: Reference number for the consignee.

custom_field1

• Type: String
• Description: Custom field for additional information.

vendor_id

• Type: String
• Description: The unique identifier for the vendor associated with the dispatch.

dispatch_stops

• Type: Array of Objects
• Description: A list of stops associated with the dispatch.

id

• Type: Integer
• Description: The unique identifier for the stop.

bill_of_lading

• Type: String
• Description: Bill of lading information.

comments

• Type: String
• Description: Additional comments for the stop.

dispatch_location_id

• Type: Integer
• Description: The unique identifier for the dispatch location.

driver_load

• Type: String
• Description: Driver load information.

early_date

• Type: String (DateTime)
• Description: The earliest date and time for the stop.

form_ids

• Type: Array of Strings
• Description: List of form IDs associated with the stop.

late_date

• Type: String (DateTime)
• Description: The latest date and time for the stop.

number

• Type: Integer
• Description: The sequence number of the stop in the dispatch.

pallets_in

• Type: Integer
• Description: Number of pallets in.

pallets_out

• Type: Integer
• Description: Number of pallets out.

pieces

• Type: Integer
• Description: Number of pieces associated with the stop.

status

• Type: String
• Description: The current status of the stop (e.g., "available").

type

• Type: String
• Description: Type of the stop (e.g., "pickup").

volume

• Type: Float
• Description: Volume of goods at the stop.

weight

• Type: Float
• Description: Weight of goods at the stop.

form_entry_ids

• Type: Object
• Description: Entry IDs for the forms associated with the stop.

dispatch_trip_id

• Type: Integer
• Description: The unique identifier for the dispatch trip associated with the stop.

custom_field1

• Type: String
• Description: Custom field for additional information.

vendor_id

• Type: String
• Description: The unique identifier for the vendor associated with the stop.

vendor_dispatch_location_id

• Type: String
• Description: The unique identifier for the vendor dispatch location.

dispatch_trips

• Type: Array of Objects
• Description: A list of trips associated with the dispatch.

id

• Type: Integer
• Description: The unique identifier for the dispatch trip.

status

• Type: String
• Description: The current status of the dispatch trip (e.g., "not_started").

status_updated_at

• Type: String (DateTime)
• Description: The timestamp of the last status update for the dispatch trip.

loaded_miles

• Type: Integer
• Description: Loaded miles for the dispatch trip.

vendor_id

• Type: String
• Description: The unique identifier for the vendor associated with the dispatch trip.

driver_id

• Type: Integer
• Description: The unique identifier for the driver associated with the dispatch trip.

vehicle_id

• Type: Integer
• Description: The unique identifier for the vehicle associated with the dispatch trip.