Appointments
Stage service appointments before creating moves
Appointments are staging records that allow you to register upcoming service appointments in HopDrive before a transportation type has been selected. Once a customer elects a HopDrive service, the appointment is upgraded and HopDrive handles move creation internally.
Requests made to this endpoint require an authorization header using your authentication token.
How it works
- Create an appointment with
POST /v1/appointmentsas soon as you have appointment data, even if the pickup address or other details are incomplete. - Replace or upgrade the appointment with
PUT /v1/appointments/:idto fully replace all mutable fields, including electing a transportation type. - Partially update the appointment with
PATCH /v1/appointments/:idto modify specific fields without affecting others.
Appointment Lifecycle
Appointments progress through the following states:
| Status | Description |
|---|---|
new | Record created. Initial state after POST. |
pending | Flagged for resolution — missing or invalid data (e.g., no pickup address). |
ready | Transportation type elected. HopDrive begins internal move staging. |
paying | Consumer payment in progress (consumer-pay path only). |
paid | Payment complete. Move creation triggered internally. |
canceled | Appointment canceled. |
refunded | Payment refunded after cancellation. |
failed | Payment or processing failure. |
Your integration covers the new → ready transition. All subsequent state changes are handled internally by HopDrive.
Supported Transportation Types
When upgrading an appointment via PUT, provide one of the following transportation_type values:
| Value | Description |
|---|---|
valet | Driver picks up the vehicle from the consumer and delivers it to the dealership. |
mobile_service | Mobile service van dispatched to the consumer's location. |
shuttle | Dealer shuttle route management. |
rideshare | Third-party rideshare coordination. |
Update Restrictions
Appointments in a terminal state (canceled, refunded, failed) or with a past appointment time cannot be modified via PUT or PATCH.
When an appointment reaches ready, paying, or paid status, move staging has begun. At that point, only the following fields can be modified via PATCH:
consumer_name,consumer_phone,driver_notes,config
Location, vehicle, and scheduling fields are frozen once staging begins.
Handling Incomplete Data
You should create an appointment even if data is incomplete or the pickup address is unavailable. Appointments with missing required data will be flagged as pending and surfaced to the dealer for resolution. No move will be created from an unresolved appointment.