For an example of how to use our /dispatches endpoints in a typical business scenario, refer to TMS Integration Workflow.
Dispatch is a collection of stops, each with its own set of forms, which can be in either a planned, active, canceled, or completed state. A driver can have only one active dispatch while having any number of planned dispatches.
A dispatch consists of a minimum of two stops. The first is called the shipper stop and the last is called the consignee stop. The shipper stop is where the dispatch is started from and the consignee stop is where the dispatch is completed. Any other stops in between are referred to as additional stops and are called dispatch stops in our system.
A dispatch trip is a collection of dispatch stops. Dispatches in v2 can be broken down as a series of trips. In the most straightforward case, a dispatch could comprise of one dispatch trip. However, we can add more trips to split up a dispatch, the first trip will always be the trip that includes the shipper stop and the last trip will be the one that includes the consignee stop. Each trip would have its own stops and the stops need to be unique across trips.
Below is a list of all attributes in a Dispatch
| Attribute | Type | Description |
|---|---|---|
| vendor_id | string (optional) | External system ID for dispatch |
| vendor_shipper_id | string (optional) | External system ID for shipper stop |
| vendor_consignee_id | string (optional) | External system ID for consignee stop |
| shipper_dispatch_location_id | integer (required) | Dispatch location associated with shipper stop for dispatch |
| consignee_dispatch_location_id | integer (required) | Dispatch location associated with consignee stop for dispatch |
| status | string (required) | Status of dispatch. Valid values are [“planned”, “active”, “cancelled”, “completed”] |
| shipper_status | string (required) | Status for shipper stop. Valid values are ["available", "in_progress", "departed"]. Default value: "available" |
| consignee_status | string (required) | Status for consignee stop. Valid values are ["available", "in_progress", "departed"]. Default value: "available" |
| shipper_form_ids | Array of strings (required) | Forms to be filled out at shipper stop. Array of UUID’s of forms. |
| consignee_form_ids | Array of strings (required) | Forms to be filled out at consignee stop. Array of UUID’s of forms. |
| shipper_type | string (required) | |
| consignee_type | string (required) | |
| trailer | string (optional) | |
| product | string (optional) | |
| additional_pickups | integer (optional) | |
| additional_drops | integer (optional) | |
| loaded_miles | integer (optional) | |
| consignee_refno | string (optional) | |
| temperature_min | integer (optional) | |
| temperature_max | integer (optional) | |
| pickup_number | string (optional) | |
| pickup_early_date | datetime (optional) | |
| pickup_late_date | datetime (optional) | |
| shipper_driver_load | boolean (optional) | |
| shipper_pieces | float (optional) | |
| shipper_weight | float (optional) | |
| shipper_pallets | integer (optional) | |
| shipper_comments | string (optional) | |
| shipper_bill_of_lading | string (optional) | |
| shipper_volume | float (optional) | |
| delivery_early_date | datetime (optional) | |
| delivery_late_date | datetime (optional) | |
| consignee_driver_load | boolean (optional) | |
| consignee_pieces | float (optional) | |
| consignee_weight | float (optional) | |
| consignee_pallets | integer (optional) | |
| consignee_comments | string (optional) | |
| consignee_bill_of_lading | string (optional) | |
| consignee_volume | float (optional) | |
| order_pieces | float (optional) | |
| order_weight | float (optional) | |
| order_volume | float (optional) | |
| custom_field1-10 | string (optional) | 100 custom fields to store any extra information for a dispatch |
| shipper_custom_field1-100 | string (optional) | 100 custom fields to store any extra information for a shipper stop |
| consignee_custom_field1-100 | string (optional) | 100 custom fields to store any extra information for a consignee stop |
| auto_complete_forms | boolean (optional) |
Below is a list of all attributes in a Dispatch Stop
| Attribute | Type | Description |
|---|---|---|
| vendor_id | string (optional) | External system ID for stop |
| number | integer (required) | Specifies the position of the stop. Values start at 1 |
| status | string (required) | Status of stop. Valid values are ["available", "in_progress", "departed"]. Default value: "available" |
| dispatch_location_id | integer (required) | Dispatch location associated with stop |
| form_ids | Array of strings (required) | Forms to be filled out at stop. Array of UUID’s of forms. |
| type | string (optional) | |
| early_date | datetime (optional) | |
| late_date | datetime (optional) | |
| driver_load | boolean (optional) | |
| pieces | float (optional) | |
| weight | float (optional) | |
| pallets_in | integer (optional) | |
| pallets_out | integer (optional) | |
| comments | string (optional) | |
| bill_of_lading | string (optional) | |
| volume | float (optional) | |
| custom_field1-100 | string (optional) | 100 custom fields to store any extra information for a stop |
Below is a list of all attributes in a Dispatch Trip
| Attribute | Type | Description |
|---|---|---|
| vendor_id | string (optional) | External system ID for trip |
| status | string (required) | Status of trip. Valid values are ["not_started", "in_progress", "completed", "cancelled"]. Default value: "not_started" |
| vehicle_id | integer (required) | Vehicle associated to dispatch |
| driver_id | integer (required) | Driver associated to dispatch |
| dispatch_id | integer (required) | dispatch that the trip is associated with |
| status_updated_at | timestamp | |
| created_at | timestamp | |
| updated_at | timestamp |