Move Object

A successful POST to a moves endpoint will return a modified request object, including additional information about the move or pair of moves.

For unsuccessful requests, please refer to Error Handling and Error Codes.

Additional Fields

For each individual move, the following new fields are included in the response:

move_uri - A URI string referencing the /moves resource for the associated move created
lane_uri - A URI string referencing the /lanes resource for the lane (pickup and delivery location pair) associated with the move created
status - The current status of the move
rooftop - The rooftop the move was created for
settled - A move will be marked as settled 7 days after being completed. This means that the move's charge (see charge object) has been finalized and the move is ready to be invoiced.
cancel_status - If a cancellation has been requested, the current status will be reflected here
pickup_started - Timestamp for when the pickup portion of the move was started
pickup_arrived - Timestamp for when the driver arrived at the pickup location
pickup_successful - Timestamp for when the pickup portion of the move was completed
delivery_started - Timestamp for when the delivery portion of the move was started
delivery_arrived - Timestamp for when the driver arrived at the delivery location
delivery_successful - Timestamp for when the delivery portion of the move was completed
tracking_link - URL to a live tracking map of the move
workflowset - The workflow set used to define pickup and delivery workflows to use on the move
earliest_available_time - The earliest time the move can be started based on the location's availability (Business hours, holidays, etc.)
message - If the earliest_available_time is affected by a holiday or other closure, a description of the closure will be included here
driver_name - The name of the driver assigned to the move, if one has been assigned
usecase_key - The use-case key describing the type of workflow this move is part of. See Usecase Keys below for possible values.
scenario_key - The scenario key from the dispatch scenario associated with this move. See Scenario Types below for possible values.
consumer_at_pickup - Boolean indicating whether the consumer is at the pickup location. true means the consumer's vehicle is being picked up from the consumer's location; false means the vehicle is at the dealership/service location. Set during move creation in the move planner. Defaults to false.
parent_scenario - Object containing the dispatch scenario this move belongs to, including all sibling moves in the scenario. See Parent Scenario Object below for details.

When a request is sent, the individual location fields are parsed, combined, and sent through Google's Places API in order to cleanse and retrieve a known, standardized location. For each location object within a move, the following new fields are included in the response for comparison:

lat - The latitude associated with the found location
lon - The longitude associated with the found location
google_place_id - The ID used by Google to identify the found location
location_id - The ID assigned to the location by HopDrive that can be used to retrieve information through the /locations resource
full_address - The full address as returned by the Google Places API, this can be compared to the fields on the request object to ensure accuracy

Usecase Keys

The usecase_key field indicates the type of workflow the move is part of.

Key	Description
`round-trip`	Round Trip
`one-way`	One way
`concierge-pu`	Concierge Pickup
`concierge-ret`	Concierge Return
`concierge-loaner-pu`	Concierge + Loaner pickup
`concierge-loaner-ret`	Concierge + Loaner return
`one-way-hangtag`	One way with hangtag staged indicator
`concierge-hangtag`	One way concierge with hangtag return ready indicator
`concierge-loaner-hangtag`	Concierge + loaner with hangtag return ready indicator
`one-way-shuttle`	One way move with a customer provided shuttle
`one-way-hangtag-shuttle`	One Way Shuttle with hangtag staged indicator

Parent Scenario Object

The parent_scenario object describes the dispatch scenario that the current move belongs to. A scenario is a planned sequence of moves that together accomplish a single unit of work (e.g., a concierge pickup with a loaner swap, or a round trip). Each move in a webhook payload is one step in that sequence.

Use parent_scenario to understand:

Where this move fits in the overall sequence (via cardinality, a zero-based index)
What the other moves in the scenario are and their roles (via the moves array)
Which move is the loaner vs the consumer vehicle in concierge-loaner scenarios (via consumer_type)

Fields

Field	Type	Description
`cardinality`	integer	Zero-based position of the current move within the scenario sequence
`scenario_key`	string	The scenario type key (see Scenario Execution Plans below)
`moves`	array	All moves in the scenario, ordered by their position in the execution plan

Each entry in the moves array contains:

Field	Type	Description
`cardinality`	integer	Zero-based position of this move in the sequence
`id`	integer	The move ID
`move_type`	string	`"drive"` or `"ride"`
`usecase_key`	string	The use case key for this move
`pickup_time`	string/null	Timestamp when pickup was started, or `null` if not yet started
`consumer_at_pickup`	boolean	Whether the consumer is at the pickup location
`consumer_type`	string/null	`"loaner"`, `"customer"`, or `null` for non-concierge moves

How to read the execution plan

The cardinality value (0, 1, 2) maps directly to the move's position in the scenario's execution plan. For example, in a concierge-loaner-pu scenario:

Cardinality 0 = Move 1 in the execution plan = Loaner vehicle move
Cardinality 1 = Move 2 in the execution plan = Concierge (consumer vehicle) move

By combining cardinality with the scenario_key, you can determine exactly what role each move plays. The consumer_type field ("loaner" or "customer") on concierge-loaner moves provides an additional explicit signal.

Example: Concierge + Loaner Pickup

In this scenario, a loaner vehicle is delivered to the consumer first, then the consumer's vehicle is picked up and driven to the dealership.

"parent_scenario": {
  "cardinality": 0,
  "scenario_key": "concierge-loaner-pu",
  "moves": [
    {
      "cardinality": 0,
      "id": 73637,
      "move_type": "drive",
      "usecase_key": "concierge-loaner-pu",
      "pickup_time": "2026-03-28T00:14:00+00:00",
      "consumer_at_pickup": false,
      "consumer_type": "loaner"
    },
    {
      "cardinality": 1,
      "id": 73638,
      "move_type": "drive",
      "usecase_key": "concierge-loaner-pu",
      "pickup_time": "2026-03-27T23:35:57+00:00",
      "consumer_at_pickup": true,
      "consumer_type": "customer"
    }
  ]
}

In this example, the webhook is for move 73637 (cardinality 0), which is the loaner vehicle being delivered. Move 73638 (cardinality 1) is the consumer's vehicle being picked up.

Scenario Execution Plans

Each scenario defines an ordered execution plan of moves. The cardinality value in parent_scenario maps to the move's position in this plan (0 = Move 1, 1 = Move 2, etc.).

Move type legend:

Drive A — The primary drive move (the vehicle being transported for the customer)
Drive B — The secondary/return drive move in a round trip
Drive A/B — Either drive in a flexible-sequence round trip (can be performed in any order)
Ride — A rideshare for the driver to get to or from a location
Concierge — A drive of the consumer's vehicle
Loaner — A drive of the dealership's loaner vehicle
Shuttle — A shuttle ride (internal or customer-provided)

Concierge and Loaner Scenarios

Scenario Key	Name	Move 1	Move 2	Notes
`concierge-pu`	Concierge with Vehicle at Consumer	Ride	Concierge	Sequenced so driver always starts at the dealership
`concierge-ret`	Concierge with Vehicle at Dealership	Concierge	Ride	Sequenced so driver always starts at the dealership
`concierge-pu-no-rideshare`	Concierge with Vehicle at Consumer with no Rideshare	Concierge		No rideshare before; driver goes directly to consumer location
`concierge-ret-no-rideshare`	Concierge with Vehicle at Service with No Rideshare	Concierge		No rideshare after; driver returns independently
`concierge-loaner-pu`	Concierge + Loaner with Vehicle at Consumer	Loaner	Concierge	Sequenced so driver always starts at the dealership
`concierge-loaner-ret`	Concierge + Loaner with Vehicle at Dealership	Concierge	Loaner	Sequenced so driver always starts at the dealership

One-Way Scenarios

Scenario Key	Name	Move 1	Move 2	Move 3	Notes
`base`	Base move (no ride needed)	Drive A
`stranded-no-rideshare`	Stranded with no rides	Drive A			Driver arranges their own return independently
`stranded-rideshare-before`	Ride before stranded	Ride	Drive A
`stranded-rideshare-after`	Stranded with ride after	Drive A	Ride
`stranded-rideshare-both`	Stranded with ride on both sides	Ride	Drive A	Ride
`stranded-shuttle-after`	Stranded with shuttle after	Drive A	Shuttle		HopDrive internal shuttle
`triangle`	Triangle	Ride	Drive A	Ride	Requires customer config enablement

Hangtag Scenarios

Hangtag scenarios are triggered when a hangtag is scanned, indicating a vehicle is staged or a concierge is ready for return.

Scenario Key	Name	Move 1	Move 2	Notes
`stranded-rideshare-after`	One-way hangtag with ride after	Drive A	Ride	Hangtag scanned indicating staged
`stranded-rideshare-before`	One-way hangtag ride before	Ride	Drive A	Hangtag scanned indicating staged
`concierge-pu`	Concierge hangtag	Ride	Concierge	Hangtag scanned indicating concierge ready for return
`concierge-loaner-pu`	Concierge + loaner hangtag	Loaner	Concierge	Hangtag scanned indicating concierge ready for return

Round Trip Scenarios

Scenario Key	Name	Move 1	Move 2	Notes
`round-trip`	Round trip (strict order)	Drive A	Drive B	Moves must be performed in sequence
`round-trip-flex`	Round trip (flexible order)	Drive A/B	Drive A/B	Moves can be performed in any order
`round-trip-rideshare-before`	Round trip with ride before	Ride	Drive A
`round-trip-rideshare-after`	Round trip with ride after	Drive A	Ride
`round-trip-rideshare-both`	Round trip with rides on both sides	Ride	Drive A	Ride
`round-trip-flex-rideshare-before`	Flexible round trip with ride before	Ride	Drive A
`round-trip-flex-rideshare-after`	Flexible round trip with ride after	Drive A	Ride
`round-trip-flex-rideshare-both`	Flexible round trip with rides on both sides	Ride	Drive A	Ride

Shuttle and Internal Scenarios

Scenario Key	Name	Move 1	Move 2	Notes
`shuttle-linker`	Shuttle linker	Drive A		Links drivers between lanes to optimize group plans
`shuttle-drive`	Shuttle driver providing rides	Drive A	Drive B
`shuttle-run`	Shuttle run	Multi-stop		Shuttle driver executing a multi-stop passenger route
`mobile-service-run`	Mobile service run	Multi-stop		Mobile technician executing a multi-stop service route
`parts-delivery-route`	Parts delivery route	Multi-stop		Delivery driver executing a multi-stop parts delivery route

Additional Fields​

Usecase Keys​

Parent Scenario Object​

Fields​

How to read the execution plan​

Example: Concierge + Loaner Pickup​

Scenario Execution Plans​

Concierge and Loaner Scenarios​

One-Way Scenarios​

Hangtag Scenarios​

Round Trip Scenarios​

Shuttle and Internal Scenarios​