Skip to content
API Reference
/
/
List Appointments

Hero Health Public API (1.0.0)

The Hero Health Public API enables healthtech partners to integrate with NHS GP practices connected to EMIS Web and TPP SystmOne.

Key capabilities

  • Patient messaging — Send SMS, email, and NHS App messages on behalf of a practice
  • Appointment booking — List available slots, create reservations, and confirm bookings
  • Patient management — Register and look up patients via PDS (Personal Demographics Service)
  • Webhooks — Subscribe to events such as appointment confirmations and write-to-record outcomes
  • Booking & form links — Generate sharable links for patient self-service flows
  • Elements — Generate access tokens for embedding pre-built Hero UI components

Authentication

All endpoints require an x-api-key and x-practice-group-id header. API keys are scoped to specific functionality (messaging, booking, booking links). Contact Hero support to request your key.

Rate limits

Rate limits are defined in your Partner agreement. If you exceed your limit you will receive a 429 Too Many Requests response.

Download OpenAPI description
Download API docs
Languages
Servers
Mock server
https://developer.herohealth.net/_mock/apis/public-api/openapi/
Staging
https://api.staging.htech.app/
Production
https://api.herohealth.net/

Practice Group

Manage practice group settings, access tokens, and configuration. Use the access token endpoint to generate short-lived JWTs for Hero Elements.

Operations

Patients

Register, search, and manage patient records. Supports PDS (Personal Demographics Service) lookups to trace patients against the NHS Spine.

Operations

Messages

Send SMS, email, NHS App, and Hero-only messages to patients. Supports write-to-record to persist messages in the patient's EHR.

Operations

Booking

Create appointment reservations, confirm bookings, cancel, and reschedule. Query available slots filtered by location, practitioner, and appointment type.

Operations

Check slot availability

Request

Check whether a specific slot is still available for booking. Call this immediately before creating an appointment to avoid reservation conflicts.

Security
apiKeyAuth and practiceGroupId
Bodyapplication/jsonrequired
practitioner_idstring^\d+$required
appointment_type_idstring^\d+$required
location_idstring^\d+$required
start_timestring(date-time)required

ISO 8601 date format

Example: "1989-04-11"
durationnumberrequired
curl -i -X POST \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/slots/availability \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE' \
  -d '{
    "practitioner_id": "string",
    "appointment_type_id": "string",
    "location_id": "string",
    "start_time": "1989-04-11",
    "duration": 0
  }'

Responses

Ok

Bodyapplication/json
availablebooleanrequired
Response
application/json
{
  "available": true
}

List Appointments

Request

Retrieves a list of all appointments.

Security
apiKeyAuth and practiceGroupId
Query
page_indexstring
page_sizestring
order_bystring
Enum"patient_id""patient_first_name""patient_last_name""patient_full_name""practitioner_first_name""practitioner_last_name""practitioner_full_name""appointment_template_name""appointment_source""location_name"
order_descendingboolean
patient_idstring
patient_first_namestring
patient_last_namestring
patient_full_namestring
practitioner_idstring or Array of strings
One of:
string
practitioner_first_namestring
practitioner_last_namestring
practitioner_full_namestring
location_idstring or Array of strings
One of:
string
appointment_template_namestring
location_namestring
has_been_cancelledboolean
appointment_sourcestring
Enum"Hero patient led""Hero admin led""Hero booking link""Hero booking API""EMIS""Cliniko"
start_timestring
end_timestring
curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v2/appointments?page_index=string&page_size=string&order_by=patient_id&order_descending=true&patient_id=string&patient_first_name=string&patient_last_name=string&patient_full_name=string&practitioner_id=string&practitioner_first_name=string&practitioner_last_name=string&practitioner_full_name=string&location_id=string&appointment_template_name=string&location_name=string&has_been_cancelled=true&appointment_source=Hero+patient+led&start_time=string&end_time=string' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Ok

Bodyapplication/json
dataArray of objectsrequired
data[].​idstring^\d+$required
data[].​patientobject or null
data[].​practitionerobject or null
data[].​location_idstring^\d+$required
data[].​start_timestring or null(date-time)required
data[].​reserved_untilstring or null(date-time)
data[].​booking_confirmed_atstring or null(date-time)
data[].​can_be_cancelledboolean
Default false
data[].​can_be_rescheduledboolean
Default false
data[].​cancellation_policy_hoursnumber
data[].​appointment_template_namestring or null
data[].​cancelled_atstring or null(date-time)
data[].​confirmed_atstring or null(date-time)
data[].​appointment_sourcestring or null
data[].​videoboolean or null
Default false
data[].​in_personboolean
Default false
data[].​telephoneboolean
Default false
data[].​location_namestring or null
data[].​servicestring or null
data[].​sourcestring or null
data[].​statusstring or null
data[].​appointment_type_idstring or null
data[].​durationnumber or null
data[].​patient_uidstring or null
data[].​practitioner_idstring or null
countnumberrequired
Response
application/json
{
  "data": [
    { … }
  ],
  "count": 0
}

List Automated messages

Request

Retrieves a list of automated appointment messages.

Security
apiKeyAuth and practiceGroupId
Query
page_indexstring
page_sizestring
orderBystring
Enum"createdAt""sentAt"
order_descendingstring
Enumtruefalse
recipient_idstring
statusstring or Array of strings
One of:
string
Enum"INVALIDATED""QUEUED""SENT""SUCCESS""ERROR"
notification_typestring or Array of strings
One of:
string
curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v2/automated_messages?page_index=string&page_size=string&orderBy=createdAt&order_descending=true&recipient_id=string&status=INVALIDATED&notification_type=string' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Ok

Bodyapplication/json
dataArray of objectsrequired
data[].​idstringrequired
data[].​recipientobject or null
data[].​channelstring or null
data[].​contact_detailstring or null
data[].​sent_atstring or null(date-time)
data[].​statusstring or null
data[].​message_typestring or null
data[].​appointment_idstring or null
data[].​appointment_typestring or null
data[].​appointment_start_timestring or null(date-time)
data[].​notification_typestring or null
countnumberrequired
Response
application/json
{
  "data": [
    { … }
  ],
  "count": 0
}

Episode

Manage clinical episodes — containers for related patient interactions and messages.

Operations

Care Navigation

Manage care navigation pathways and patient submissions for triage workflows.

Operations

Prescription

Create and manage prescriptions.

Operations

Prescriptions

List and manage prescriptions.

Operations

WriteToRecord

Check the status of write-to-record operations for messages sent to the EHR.

Operations

Admin

Manage admin users, signatures, and preferences within a practice group.

Operations

ApiKey

List and manage API keys for your practice group.

Operations

Task

Manage tasks assigned to admin users.

Operations

Partner

Retrieve partner information and integrations.

Operations

Partners

Retrieve partner information and integrations.

Operations

Form

List and retrieve forms (questionnaires) configured for a practice group.

Operations

Form Response

Create, retrieve, and update form responses submitted by patients.

Operations

Subscriptions

Manage notification subscriptions and subscribers.

Operations

Webhooks

Subscribe to Hero events (e.g. appointment confirmations, write-to-record outcomes) and receive real-time notifications via HTTP callbacks.

Operations

Invoicing

Manage invoicing customers, products, coupons, and membership schemes.

Operations

Utilities

Utility endpoints for address lookup and SNOMED code validation.

Operations

Booking - HCA

Specialist booking endpoints for HCA (Healthcare Assistant) diary consultants and appointments.

Operations