POST /appointments

Create a new appointment record. Call this endpoint as soon as appointment data is available, regardless of whether the customer has elected a transportation service or whether all data fields are complete.

The returned id must be persisted — it is required for the PUT /appointments/:id upgrade call.

Example Request

POST /v1/appointments

{
    "customer_id": 1234,
    "appointment_time": "2026-03-10T09:00:00-05:00",
    "consumer_name": "Jane Smith",
    "consumer_phone": "+15555550101",
    "consumer_at_pickup": true,
    "vehicle_vin": "1HGBH41JXMN109186",
    "vehicle_make": "Honda",
    "vehicle_model": "Accord",
    "vehicle_year": 2022,
    "vehicle_color": "Silver",
    "pickup_location_id": null,
    "delivery_location_id": 5678,
    "config": {}
}

Body Params

Field	Type	Required?	Description
customer_id	Number	Required	HopDrive dealer account ID. Must match an authorized rooftop on your bearer token.
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. Example: "2026-03-10T09:00:00-05:00"
consumer_name	String	Optional	Consumer full name. Used for SMS outreach.
consumer_phone	String	Optional	Consumer mobile phone number. Used for SMS outreach.
pickup_location_id	Number	Optional	HopDrive location ID for the consumer's pickup address. May be null if the address is not yet available.
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

201 /v1/appointments

{
    "id": 88001234,
    "status": "new"
}

info

Store the returned id. It is required for the PUT /appointments/:id call to upgrade the appointment with a transportation type.