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". For rooftops whose availability response reports enforcement_mode: "forced", this must land inside an offered slot's earliest_appointment_time/latest_appointment_time window (see GET /appointments/availability); the request also needs pickup_location_id or config.pickup_address so the slot check can resolve the route. Times outside every window return 400 request_invalid.
workflow_set_id	Number	Optional	Workflow set for the appointment's moves. When omitted, the rooftop's configured default_workflow_set_id applies, falling back to the public default (workflow set 1). Rooftops that disable public workflow sets and have no configured default must pass this explicitly. An explicit value must be one of the rooftop's own workflow sets or a public one, else 400 request_invalid.
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.