Skip to content
API Reference
/
/
List Practice Group Eleme...

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

List Locations

Request

Retrieves a list of all locations configured for online booking on Hero Health.

Security
apiKeyAuth and practiceGroupId
Query
appointment_type_idsArray of strings
has_availabilityboolean
curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/locations?appointment_type_ids=string&has_availability=true' \
  -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[].​namestringrequired
data[].​slot_countnumberrequired
data[].​next_available_atstring or null(date-time)required
data[].​longitudenumber or nullrequired
data[].​latitudenumber or nullrequired
countnumberrequired
Response
application/json
{
  "data": [
    { … }
  ],
  "count": 0
}

List Practice Group Elements

Request

Lists elements assigned with the authenticated Practice Group.

Security
apiKeyAuth and practiceGroupId
curl -i -X GET \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/me/elements \
  -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[].​versionstring or nullrequired
data[].​configobject
data[].​elementobject or null
countnumberrequired
Response
application/json
{
  "data": [
    { … }
  ],
  "count": 0
}

Get Practice Group

Request

Retrieves information regarding the authenticated Practice Group.

Security
apiKeyAuth and practiceGroupId
curl -i -X GET \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/me \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Ok

Bodyapplication/json
idstringrequired
namestringrequired
sectorstringrequired
Enum"nhs""paid"
write_to_recordbooleanrequired
ehr_partnerstring or nullrequired
Enum"emis""systm_one"
ehr_partner_enabledbooleanrequired
ehr_partner_settingsobject or nullrequired
One of:
ehr_partner_settings.​emis_ip_addressstring or nullrequired
ehr_partner_settings.​emis_ip_address_internalstring or nullrequired
ehr_partner_settings.​emis_supplier_idstring or nullrequired
ehr_partner_settings.​emis_usernamestring or nullrequired
ehr_partner_settings.​emis_orgidstring or nullrequired
ehr_partner_settings.​emis_user_idstring or nullrequired
ehr_partner_settings.​emis_passwordstring or nullrequired
custom_slot_to_slotbooleanrequired
use_partner_bookable_slotsbooleanrequired
data_source_prioritiesArray of stringsrequired
Items Enum"hero""emis""pds""gha""systm_one"
js_booking_servicebooleanrequired
prescription_partner_enabledbooleanrequired
prescription_partnerstring or nullrequired
Enum"signature_rx""chem4u""pharmacierge"
prescription_partner_credentialsobject or null
addressobject or nullrequired
address.​line_1stringrequired
address.​postcodestringrequired
address.​line_2string or null
address.​line_3string or null
address.​townstring or null
address.​countystring or null
address.​countrystring or null
authenticated_asobject or nullrequired
authenticated_as.​idstringrequired
authenticated_as.​first_namestringrequired
authenticated_as.​last_namestringrequired
authenticated_as.​emailstringrequired
authenticated_as.​external_prescriber_idstring or nullrequired
authenticated_as.​signaturestring or nullrequired
authenticated_as.​linked_practitioners_idstring or nullrequired
authenticated_as.​preferencesobjectrequired
authenticated_as.​preferences.​default_notification_channelstringrequired
Enum"email""sms""nhs_app_email""nhs_app_sms"
authenticated_as.​team_membershipsArray of objectsrequired
authenticated_as.​team_memberships[].​idstringrequired
authenticated_as.​team_memberships[].​namestringrequired
Response
application/json
{
  "id": "string",
  "name": "string",
  "sector": "nhs",
  "write_to_record": true,
  "ehr_partner": "emis",
  "ehr_partner_enabled": true,
  "ehr_partner_settings": {
    "emis_ip_address": "string",
    "emis_ip_address_internal": "string",
    "emis_supplier_id": "string",
    "emis_username": "string",
    "emis_orgid": "string",
    "emis_user_id": "string",
    "emis_password": "string"
  },
  "custom_slot_to_slot": true,
  "use_partner_bookable_slots": true,
  "data_source_priorities": [
    "hero"
  ],
  "js_booking_service": true,
  "prescription_partner_enabled": true,
  "prescription_partner": "signature_rx",
  "prescription_partner_credentials": {
    "email": "string"
  },
  "address": {
    "line_1": "string",
    "postcode": "string",
    "line_2": "string",
    "line_3": "string",
    "town": "string",
    "county": "string",
    "country": "string"
  },
  "authenticated_as": {
    "id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "external_prescriber_id": "string",
    "signature": "string",
    "linked_practitioners_id": "string",
    "preferences": { … },
    "team_memberships": [ … ]
  }
}

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

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