Create an Appointment

Request

Create an appointment reservation for a patient. The appointment is held in a reserved state until confirmed via the Book Appointment endpoint.

Flow: List Slots → Create Appointment (reserve) → Book Appointment (confirm).

If the reservation is not confirmed within the hold period, it will be automatically released.

The optional booking_mechanism field defaults to hero_confirmed. ehr_confirmed appointments must be managed via the v2 endpoints; v1 supports hero_confirmed only.

Security

apiKeyAuth and practiceGroupId

Bodyapplication/jsonrequired

appointment_type_idstring^\d+$required

location_idstring^\d+$required

practitioner_idstring^\d+$required

durationnumberrequired

start_timestring or null, (date-time)required

ISO 8601 date format

Example:"1989-04-11"

patient_idstring^\d+$

billpayer_idstring^\d+$

reasonstring

suppress_mailboolean

suppress_availability_checkboolean

suppress_eligibility_checkboolean

Default:true

booking_mechanismstring

Defaults to hero_confirmed. ehr_confirmed appointments must be managed via the v2 endpoints; v1 supports hero_confirmed only.

Enum:"hero_confirmed""ehr_confirmed"

curl -i -X POST \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/appointments \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE' \
  -d '{
    "appointment_type_id": "42",
    "location_id": "7",
    "practitioner_id": "15",
    "duration": 15,
    "start_time": "2026-03-15T09:30:00Z",
    "patient_id": "1234",
    "billpayer_id": "5678",
    "reason": "Annual health check",
    "suppress_mail": false,
    "suppress_availability_check": false,
    "suppress_eligibility_check": false,
    "booking_mechanism": "hero_confirmed"
  }'

Responses

Ok

Bodyapplication/json

idstring^\d+$required

reserved_untilstring or null, (date-time)required

Response

{
  "id": "string",
  "reserved_until": "2019-08-24T14:15:22Z"
}