POST /round-trip-moves
Swap two vehicles between locations. We'll deliver your first vehicle, then hop in your second and bring it right back.
Request orchestration
Send one POST request with the pickup and delivery addresses. HopDrive resolves the locations and a ready lane pair inside that request, selects the single product allowed by the authenticated rooftop's active contracts, and creates the scenario and its linked moves together.
You may send an Idempotency-Key header. Retrying the same request for the same rooftop returns the original scenario and move set with replayed: true; the first response has replayed: false. Reusing a key with a different use case, requested time, VIN, reference number, customer name, or customer phone returns HTTP 409. Keep the request body unchanged when retrying.
Successful responses retain the documented move fields and add scenario (id, scenario_key, product_key, usecase_key, and status) plus replayed. Address validation, lane preparation, product selection, workflowset ownership, and move persistence failures have distinct machine-readable error codes in the response's errors array.
Each drive leg resolves its own workflowset_id and sla_id, and carries its own reference_num, dealer_contact, special_instructions, pickup_workflow_data and delivery_workflow_data. A leg that omits one of the commercial fields inherits the value you sent for the first leg. The two workflow data objects are the exception and are never inherited, because they hold one vehicle's answers and attaching them to the other vehicle would be worse than leaving them empty.
Earlier releases refused a request whose two legs named different workflow sets. They are now honoured, so two legs can run different workflows and resolve different SLAs.
Compatibility note: gross vehicle weight on the second leg
gross_weight_lbs on the second vehicle used to be accepted, validated, and then silently dropped before the move was written: the paired writer omitted the column while the move response still tried to read it back. That was a bug, and this release fixes it rather than preserving it. Both legs now persist the weight you send, so a second leg that has always read back empty will start returning a value.
Example Request
{
"rooftop": 42,
"third_party_payer": 9,
"ready_by_time_utc": "2022-03-25T14:00:00Z",
"duplicate_check": "vehicle_vin",
"move_one": {
"dealer_contact": "Jane Smith",
"special_instructions": "Check in at service center",
"vehicle": {
"stock": "BK0018",
"vin": "5GAKRBED5BJ262438",
"year": "2011",
"make": "Buick",
"model": "Enclave",
"color": "White",
"manual": false
},
"pickup_location": {
"name": "Denny's Automobiles",
"address_one": "11161 Research Plaza Way",
"city": "Richmond",
"state": "VA",
"zip": "23236"
},
"sla_id": 1,
"workflowset_id": 3,
"pickup_workflow_data": {
"additional_field": "Hello World!"
},
"delivery_workflow_data": {
"additional_field": "Hello World!"
}
},
"move_two": {
"dealer_contact": "Hugh Man",
"vehicle": {
"stock": "MB0004",
"vin": "WDDGF4HB1CR220392",
"year": "2012",
"make": "Mercedes-Benz",
"model": "C-Class",
"color": "Black",
"manual": true
},
"pickup_location": {
"name": "Lot 4",
"address_one": "888 Broad St",
"city": "Richmond",
"state": "VA",
"zip": "23220"
},
"sla_id": 1,
"workflowset_id": 3,
"pickup_workflow_data": {
"additional_field": "Hello World!"
},
"delivery_workflow_data": {
"additional_field": "Hello World!"
}
}
}
Body Params
| Field | Type | Required? | Description |
|---|---|---|---|
| rooftop | Number | Optional | For users configured as dealer admins with the ability to create moves for multiple rooftops. Specify the id of the rooftop you wish to create the move for. |
| third_party_payer | Number | Optional | For users configured with third party payer accounts. This allows the move to be assigned to a different invoice than the rooftop specified. Use the /Payers endpoint to get a valid list of possible payers. API users' accounts can be configured to make this field required or to give this field a default value. |
| ready_by_time_utc | String | Required | The date and time in YYYY-MM-DD hh:mm:ss format, using UTC/Zulu time. Reference. |
| duplicate_check | String | Optional | Prevent duplicating an in-progress move (already in the system) by specifying a field to check. Supports "reference_num", "vehicle_stock" and "vehicle_vin". |
| reference_num | String | Optional | Internal reference ID, such as a repair order #. |
| dealer_contact | String | Optional | Point of contact for our driver when arriving at the service location. |
| special_instructions | String | Optional | Additional information, such as where to park or a number to call upon arrival. |
| stock | String | Optional | Internal stock number associated with the vehicle. |
| vin | String | Optional | Vehicle Identification Number associated with the vehicle. |
| year | String | Optional | Year the vehicle was manufactured. |
| make | String | Required* | The make of the vehicle (e.g., "Ford"). |
| model | String | Required* | The model of the vehicle (e.g., "F-150"). |
| color | String | Optional | The color of the vehicle. |
| manual | Boolean | Required | Whether or not the vehicle's transmission is manual (true) or automatic (false). |
| name | String | Optional | Name associated with the location. |
| full_address | String | Optional | The full address string of the location (Address pieces are no longer required if this field has a value). |
| address_one | String | Required* | The street address of the location. |
| address_two | String | Optional | Optional sub-address of the location. |
| city | String | Required* | The city that the location address is associated with. |
| state | String | Required* | The state that the location address is associated with. |
| zip | String | Optional | The 5-digit Zip Code that the location address is associated with. |
| pickup_workflow_data | Object | Optional | A single level deep object with name value pairs of placeholder values to preload in fields of the custom workflow defined by the workflowset |
| delivery_workflow_data | Object | Optional | A single level deep object with name value pairs of placeholder values to preload in fields of the custom workflow defined by the workflowset |
| sla_id | Number | Optional | Id of a Service Level Agreement to apply to this move. Talk with your dispatcher to setup custom SLAs. If nothing is passed here, the default SLA will be used. We recommend passing in the same SLA for both moves. |
| workflowset_id | Number | Optional | Id of a workflow set (combination pickup and delivery workflows) to apply to this move. Talk with your dispatcher to setup custom workflows. If nothing is passed here, the default workflows will be used. |
Request Object Structure
{
ready_by_time_utc,
duplicate_check,
move_one: {
reference_num,
dealer_contact,
special_instructions,
vehicle: {
stock,
vin,
year,
make,
model,
color,
manual
},
pickup_location: {
name,
full_address,
address_one,
address_two,
city,
state,
zip
},
sla_id,
workflowset_id,
pickup_workflow_data: {
additional_field
},
delivery_workflow_data: {
additional_field
}
},
move_two: {
reference_num,
dealer_contact,
special_instructions,
vehicle: {
stock,
vin,
year,
make,
model,
color,
manual
},
pickup_location: {
name,
full_address,
address_one,
address_two,
city,
state,
zip
},
sla_id,
workflowset_id,
pickup_workflow_data: {
additional_field
},
delivery_workflow_data: {
additional_field
}
}
}
Example Response
For additional information, see the response section.
{
"ready_by_time_utc": "2022-03-25T14:00:00Z",
"earliest_available_time": "2022-03-25T14:00:00Z",
"move_one": {
"move_id": 10038,
"status": null,
"cancel_status": null,
"pickup_started": null,
"pickup_arrived": null,
"pickup_successful": null,
"delivery_started": null,
"delivery_arrived": null,
"delivery_successful": null,
"tracking_link": null,
"move_uri": "https://api.hopdrive.com/v1/moves/10038",
"lane_uri": "https://api.hopdrive.com/v1/lanes/4990",
"reference_num": null,
"dealer_contact": "Jane Smith",
"special_instructions": "Check in at service center",
"vehicle": {
"stock": "BK0018",
"vin": "5GAKRBED5BJ262438",
"year": "2011",
"make": "Buick",
"model": "Enclave",
"color": "White",
"manual": false
},
"pickup_location": {
"name": "Denny's Automobiles",
"address_one": "11161 Research Plaza Way",
"city": "Richmond",
"state": "VA",
"zip": "23236",
"lat": 37.5050257,
"lon": -77.6013313,
"google_place_id": "ChIJkxCQwnBtsYkR1QqrxNduupo",
"location_id": 2246,
"full_address": "11161 Research Plaza Way, Richmond, VA 23236, USA"
},
"sla_id": 1,
"workflowset_id": 3,
"pickup_workflow_data": {
"additional_field": "Hello World!"
},
"delivery_workflow_data": {
"additional_field": "Hello World!"
}
},
"move_two": {
"move_id": 10039,
"status": null,
"cancel_status": null,
"pickup_started": null,
"pickup_arrived": null,
"pickup_successful": null,
"delivery_started": null,
"delivery_arrived": null,
"delivery_successful": null,
"tracking_link": null,
"move_uri": "https://api.hopdrive.com/v1/moves/10039",
"lane_uri": "https://api.hopdrive.com/v1/lanes/4990",
"reference_num": null,
"dealer_contact": "Hugh Man",
"special_instructions": null,
"vehicle": {
"stock": "MB0004",
"vin": "WDDGF4HB1CR220392",
"year": "2012",
"make": "Mercedes-Benz",
"model": "C-Class",
"color": "Black",
"manual": true
},
"pickup_location": {
"name": "Lot 4",
"address_one": "888 W Broad St",
"city": "Richmond",
"state": "VA",
"zip": "23220",
"lat": 37.550209,
"lon": -77.4494655,
"google_place_id": "Eic4ODggVyBCcm9hZCBTdCwgUmljaG1vbmQsIFZBIDIzMjIwLCBVU0EiGxIZChQKEgkPDdZ3SBGxiRG2k4LRA4YLvxD4Bg",
"location_id": 2141,
"full_address": "888 W Broad St, Richmond, VA 23220, USA"
},
"sla_id": 1,
"workflowset_id": 3,
"pickup_workflow_data": {
"additional_field": "Hello World!"
},
"delivery_workflow_data": {
"additional_field": "Hello World!"
}
}
}