PUT /appointments/:id

Full replacement of all mutable fields on an existing appointment. This is an idempotent operation — the entire mutable state of the appointment is replaced by the request body. Fields not included in the request body will be set to null.

To elect a transportation type and transition the appointment to ready, include transportation_type in the request body. HopDrive's internal event system stages the move automatically — no further action is required.

Cannot be called on appointments in a terminal state (canceled, refunded, failed) or with a past appointment_time.

Example Request

PUT /v1/appointments/:id

{
    "consumer_at_pickup": true,
    "delivery_location_id": 5678,
    "pickup_location_id": 9012,
    "appointment_time": "2026-03-10T09:00:00-05:00",
    "consumer_name": "Jane Smith",
    "consumer_phone": "+15555550101",
    "transportation_type": "valet",
    "vehicle_vin": "1HGBH41JXMN109186",
    "vehicle_make": "Honda",
    "vehicle_model": "Accord",
    "vehicle_year": 2022,
    "vehicle_color": "Silver",
    "vehicle_manual": false,
    "driver_notes": "Gate code 1234",
    "config": {}
}

Body Params

Field	Type	Required?	Description
consumer_at_pickup	Boolean	Required	true if the vehicle is at the consumer's location. false if the vehicle is already at the dealership.
delivery_location_id	Number	Required	HopDrive location ID for the dealership service address.
appointment_time	String	Optional	ISO 8601 timestamp for when the vehicle must arrive at the dealership. Omit or pass null to clear.
consumer_name	String	Optional	Consumer full name. Omit or pass null to clear.
consumer_phone	String	Optional	Consumer mobile phone number. Omit or pass null to clear.
pickup_location_id	Number	Optional	HopDrive location ID for the consumer's pickup address. Omit or pass null to clear.
transportation_type	String	Optional	Elected service type. Must be one of: valet, mobile_service, shuttle, rideshare. Setting this transitions the appointment to ready.
vehicle_vin	String	Optional	Vehicle Identification Number.
vehicle_make	String	Optional	Vehicle make (e.g., "Honda").
vehicle_model	String	Optional	Vehicle model (e.g., "Accord").
vehicle_year	Number	Optional	Vehicle model year.
vehicle_color	String	Optional	Vehicle color.
vehicle_manual	Boolean	Optional	true if the vehicle has a manual transmission.
driver_notes	String	Optional	Gate codes, special pickup instructions, or other notes for the driver.
config	Object	Optional	Flexible JSONB metadata object for integration-specific keys.

Example Response

200 /v1/appointments/:id

{
    "id": 88001234,
    "status": "ready",
    "customer_id": 1234,
    "appointment_time": "2026-03-10T14:00:00+00:00",
    "consumer_name": "Jane Smith",
    "consumer_phone": "+15555550101",
    "consumer_at_pickup": true,
    "pickup_location_id": 9012,
    "delivery_location_id": 5678,
    "vehicle_vin": "1HGBH41JXMN109186",
    "vehicle_make": "Honda",
    "vehicle_model": "Accord",
    "vehicle_year": 2022,
    "vehicle_color": "Silver",
    "vehicle_manual": false,
    "driver_notes": "Gate code 1234",
    "move_id": null,
    "config": { "transportation_type": "valet" },
    "updatedat": "2026-03-05T18:30:00.000000+00:00"
}

info

The move_id field is populated asynchronously by HopDrive after the move is staged internally. It will be null in the immediate response.