Skip to content

Driver Plans Structure

The GET /drivers/{id}/plans endpoint returns driver plan information, showing scheduled moves and events assigned to a driver for a given time period, including both shipment and non-shipment activities.

After reading this article you will understand:

  • How to retrieve driver plans and apply date filters
  • How to update event arrival and departure times
  • Driver plans structure: top-level properties, moves, and events
  • How moves organize work assignments and track status
  • How events represent actions at locations for shipment and non-shipment work

Overview

A driver plan is organized as an array of items, each representing a planned move for the driver. Each move is composed of events that define actions at specific locations that the driver should complete. The order of moves is chronological.

Driver plans are read-only. You retrieve them through GET /drivers/{id}/plans and update event times through separate APIs depending on the event type. See Move Event Types for a complete list of event types.

Retrieving Driver Plans

Use the GET /drivers/{id}/plans endpoint to retrieve a driver's schedule.

Endpoint

GET /drivers/{driverId}/plans

Query Parameters

Filter the plan results by date range:

  • startDate: Beginning date for plan retrieval (ISO date format: YYYY-MM-DD). Defaults to today if not specified.
  • endDate: Ending date for plan retrieval (ISO date format: YYYY-MM-DD). Optional parameter to limit the date range.

Examples

GET /drivers/100/plans
GET /drivers/100/plans?startDate=2020-12-14
GET /drivers/100/plans?startDate=2020-12-14&endDate=2020-12-20

Date Range Rules

ℹ️ If endDate is not provided, the response will include all moves from startDate onward.

⚠️ If endDate is provided without startDate, the request will return a 400 Bad Request error. The startDate must be earlier than or equal to endDate.

Response Examples

For complete examples of driver plans with shipment events and non-shipment events, refer to the Driver Plans API Reference documentation under GET /drivers/{id}/plans response examples.

Updating Driver Plans

Driver plans are read-only. You cannot update them directly through the /drivers/{id}/plans endpoint. Instead, updates must be made through different APIs depending on whether the event is a shipment event type or is a non-shipment (ns-) event type.

Determining Shipment vs. Non-Shipment Events

  • Shipment Events: The event type is a shipment event type if it is not prefixed with "ns-". These events are associated with a shipment and the parent move has a valid shipment reference.
  • Non-Shipment Events: The event type is prefixed with "ns-". These events are not associated with a shipment, and cannot be correlated to a shipment itinerary event.

Which API to Use

Update Shipment Events Through the Shipment Itinerary API

  • The move has a shipment ID (the shipment.id field is not empty) and the event type is a shipment event type (e.g., hook-origin, drop-destination)
  • Endpoint: PUT /shipments/{id}/itinerary

Update a Driver's Non-Shipment Events Through the Non-Shipment Events API

  • The event type starts with "ns-" (e.g., "ns-new-trip", "ns-hook-trailer")
  • The event has an id field
  • The move's shipment.id is empty and cannot be used to identify the event
  • Endpoint: PUT /drivers/{driverId}/non-shipment-events/{eventId}

How Updates Work

Regardless of which API you use, the behavior for updating events is consistent:

Updating Arrival Times:

  • Setting arrived changes the move status from "pending" to "progress"
  • You can set arrival without setting departure

Updating Departure Times:

  • Setting departed automatically sets completed to true
  • When the last event in a move is departed, the entire move status changes to "completed"

Updating Shipment Events

For events associated with shipments (moves where shipment.id is not empty), use the Shipment Itinerary API:

  • Endpoint: PUT /shipments/{id}/itinerary
  • Event Identification: Use the shipment ID from the parent move object's shipment.id
  • Update Method: Send the complete itinerary structure with updated event times
  • Key Challenge: Events don't have IDs in shipment contexts, so you must match them by the assigned driver, planned date, event type, site, and completed status.

⚠️ Important: Retrieve the current shipment itinerary first using GET /shipments/{id}/itinerary, then send the complete structure back with your updates.

For detailed guidance on updating shipment itineraries, see Shipment Itinerary Updates.

Example Matching Logic

To identify the correct event within the full shipment itinerary, match the following fields from the driver plan event:

  • Driver: Assigned driver ID (e.g., "100")
  • Type: Event type (e.g., "hook-loaded")
  • Site: Site ID (e.g., "111")
  • Date: Planned date (e.g., "2020-02-27")

Tip: If identical keys exist, update the first non-completed event that matches.

Updating Non-Shipment Events

For non-shipment events (events where type starts with "ns-"), use the Non-Shipment Events API:

Endpoint: PUT /drivers/{driverId}/non-shipment-events/{eventId}

This API is simpler than the shipment itinerary API because:

  • You can update individual events directly without retrieving the entire plan
  • Non-shipment events have an id property that uniquely identifies them
  • You only need the driver ID and event ID from the driver plan

Updatable Properties:

  • arrived: Arrival time at the location
  • departed: Departure time from the location
  • completed: Completion status (automatically set to true when departed is set)
  • note: Additional notes about the event

Example Request:

PUT /drivers/100/non-shipment-events/5678

Minimum Request Body:

{
  "arrived": "2020-02-28T07:15:00",
  "departed": "2020-02-28T07:45:00",
  "note": "Fuel stop completed"
}

Response:

The response returns the updated non-shipment event object with full details after the update. This can be used to synchronize your local data in the driver plan. For full API examples on updating non-shipment events, see Drivers Service Endpoints.

Validation Rules:

  • Cannot remove arrival time if the event has already departed
  • Event ID must exist and be associated with the specified driver ID
  • Departure time cannot be earlier than arrival time

💡 Best Practice: Before updating, retrieve the latest driver plan to ensure you have current event data. This helps prevent conflicts from concurrent updates.

Plan Structure

This section describes the structure of the driver plans response in detail.

Top-Level Structure

{
  "self": "/drivers/100/plans?startDate=2020-12-14&endDate=2020-12-20",
  "driver": { ... },
  "items": [ ... ]
}
  • self: URI reference to this driver plans resource, including any query parameters.
  • driver: Reference to the driver whose plans are being retrieved.
  • items: Ordered list of moves representing the driver's work schedule.

Driver Reference

"driver": {
  "id": "100",
  "href": "/drivers/100",
  "type": "driver"
}

Links back to the driver with their ID, API endpoint, and type designation.

Items (Moves)

Items is an array of move objects. A move represents a single work assignment in the driver's schedule and may be composed of one or more events that can be completed by the driver. Moves are ordered chronologically and should be completed in the order they appear.

{
  "shipment": { ... },
  "events": [ ... ],
  "plannedDate": "2020-02-27",
  "powerUnit": { ... },
  "status": "progress",
  "hint": "12345"
}
  • shipment: Reference to the shipment associated with this move, or empty if the move contains only non-shipment events.
  • events: Ordered list of events for this move.
  • plannedDate: The date this move is planned to occur (ISO date format). This is within the start date to end date range specified in the query parameters.
  • powerUnit: Reference to the tractor or truck assigned to this move.
  • status: Current status of the move. Possible values: "pending", "accepted", "rejected", "progress", "completed". The "accepted" and "rejected" statuses are only applicable if driver acceptance is supported in the TMS.
  • hint: Reference number for the move, typically the first event ID in the move. Note that this is not to be relied upon as a unique identifier for the move, as a move may be modified by adding or removing events in the shipments itinerary API.

Shipment Reference

The shipment associated with this move. For non-shipment moves, all fields will be empty strings.

"shipment": {
  "id": "12345",
  "href": "/shipments/12345",
  "orderNumber": "12345"
}
  • id: Unique identifier for the shipment, or empty string for non-shipment moves.
  • href: API endpoint to retrieve shipment details, or empty string for non-shipment moves.
  • orderNumber: Shipment order number, or empty string for non-shipment moves.

Power Unit

The tractor or truck assigned to this move. May be empty if no power unit is assigned.

"powerUnit": {
  "id": "10000123",
  "href": "/equipment/tractors/10000123"
}
  • id: Unique identifier for the power unit (tractor or truck), or empty string if not assigned.
  • href: API endpoint to retrieve full power unit details, or empty string if not assigned.

Move Status

The status field indicates the current state of the move:

  • pending: Move has been planned but not yet started or accepted by the driver.
  • accepted: Driver has accepted the move assignment. (This status is only applicable if driver acceptance is supported in the TMS.)
  • rejected: Driver has rejected the move assignment. (This status is only applicable if driver acceptance is supported in the TMS.)
  • progress: Move has started (at least one event has an arrival time set).
  • completed: All events in the move have been completed (all events have departure times set).

Events

An event represents a specific action at a location, such as picking up or dropping off equipment, or performing a non-shipment activity like refueling. Events within a move are ordered chronologically.

All events share the following common event structure:

{
  "type": "hook-origin",
  "site": { ... },
  "scheduled": "2020-02-27T08:00:00",
  "appointment": { ... },
  "arrived": "2020-02-27T08:30:00",
  "departed": "2020-02-27T09:00:00",
  "completed": true,
  "note": "Driver arrived on time"
}
  • type: Type of event. See Move Event Types for complete list of shipment event types and non-shipment event types.
  • site: Location reference where the event occurs.
  • scheduled: When the event is scheduled to occur (internal planning time).
  • appointment: Appointment window details agreed upon with the site.
  • arrived: Actual arrival time at the site, or empty string if not yet arrived.
  • departed: Actual departure time from the site, or empty string if not yet departed.
  • completed: Boolean indicating whether the event has been completed.
  • note: Optional note or comment about the event.

ℹ️ Event Identification: Non-shipment events include an id property used for updates via the non-shipment events API. Shipment events do not have an id property.

ℹ️ The scheduled time represents internal planning, while the appointment defines the time window the driver must adhere to when arriving at the location. The driver is expected to arrive within the appointment window.

Appointment Window

The appointment window specifies the time range and confirmation number for the site visit.

"appointment": {
  "start": "2020-02-27T08:00:00",
  "end": "2020-02-27T10:00:00",
  "number": "APT123"
}
  • start: Appointment window start time (ISO datetime format), or empty string if not specified.
  • end: Appointment window end time (ISO datetime format), or empty string if not specified.
  • number: Appointment confirmation number, or empty string if not specified.

Site Information

The location where the event takes place. The site includes full address details for navigation purposes.

"site": {
  "id": "111",
  "href": "/locations/sites/111",
  "name": "Customer Distribution Center",
  "address1": "100 WASHINGTON ST.",
  "city": "DOVER",
  "state": "NH",
  "zip": "03878",
  "country": "US",
  "signatureRequired": true
}
  • id: Unique identifier for the location.
  • href: API endpoint to retrieve full location details.
  • name: Location name.
  • address1: Street address.
  • city: City name.
  • state: State/province code.
  • zip: Postal code.
  • country: ISO country code (2 characters).
  • signatureRequired: Boolean indicating whether a signature is required at this location.

Event-Specific Fields

Some event types may include additional fields specific to that event type. Refer to the Move Event Types documentation for details on event-specific properties.

Conclusion

You now understand the driver plans structure, including how moves organize work assignments and events define actions at locations. You know how to retrieve driver schedules and update event arrival and departure times through the appropriate API endpoints: the shipment itinerary API for shipment events and the non-shipment events API. This enables you to effectively track driver progress and maintain accurate activity records.