Skip to content
/Form Response

Hero Health Public API (1.0.0)

The Hero Health Public API enables healthtech partners to build products that leverage Hero Health's IM1-assured EMIS/TPP integrated functionality.

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

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.

Task

Manage tasks assigned to admin users.

Operations

Partner

Retrieve partner information and integrations.

Operations

Partners

Retrieve partner information and integrations.

Form

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

Operations

Form Response

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

Operations

Get FormResponse

Request

Get a form response and its fields.

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

Responses

Ok

Bodyapplication/json
idnumberrequired
form_idnumberrequired
client_idnumberrequired
appointment_idnumber or nullrequired
invoice_idnumber or nullrequired
practice_group_idnumberrequired
created_atstring(date-time)required
updated_atstringrequired
hiddenbooleanrequired
emis_file_record_atstring or nullrequired
short_link_idnumber or nullrequired
admin_idnumber or nullrequired
write_to_record_errorstring or nullrequired
Response
application/json
{
  "id": 0,
  "form_id": 0,
  "client_id": 0,
  "appointment_id": 0,
  "invoice_id": 0,
  "practice_group_id": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "string",
  "hidden": true,
  "emis_file_record_at": "string",
  "short_link_id": 0,
  "admin_id": 0,
  "write_to_record_error": "string"
}

Get FormSubmissionResponse

Request

Get a form submission response and its fields.

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

Responses

Ok

Bodyapplication/json
idstringrequired
form_typestringrequired
Enum"questionnaire""response""appointment""care_navigation""intake_form""structured_consult"
titlestringrequired
descriptionstringrequired
patient_titlestring or nullrequired
patient_descriptionstring or nullrequired
confirmation_messagestring or nullrequired
snomed_codestring or nullrequired
fieldsArray of objectsrequired
fields[].​form_question_idstringrequired
fields[].​namestring or nullrequired
fields[].​typestringrequired
Enum"string""integer""boolean""datepicker""text""radio""dropdown""checkboxes""consent""paragraph"
fields[].​observation_namestring
Enum"systolic_blood_pressure""diastolic_blood_pressure""height""weight""body_mass_index"
fields[].​problem_namestring
Enum"asthmatic""type_2_diabetes_mellitus""heart_disease""essential_hypertension""copd""atrial_fibrillation""cerebrovascular_accident""type_1_diabetes""ischaemic_heart_disease""rheumatoid_arthritis"
fields[].​immunisation_namestring
Enum"administration_of_men_a_c_w135_and_y_vaccine""first_measles_mumps_and_rubella_vaccination_first_mmr""second_measles_mumps_and_rubella_vaccination_second_mmr"
fields[].​hintstring or null
fields[].​optionalbooleanrequired
fields[].​textstring or null
fields[].​snomed_codestring or null
fields[].​optionsArray of objects or null
fields[].​validationobject or null
fields[].​conditionsobject or null
fields[].​defaultValuestring or number or boolean or Array of strings or (string or null) or null
One of:
string
fields[].​attachment_urlstring
patient_idstring
emis_file_record_atstring or nullrequired
created_atstring(date-time)required
appointment_idnumber or nullrequired
write_to_record_statusstring or nullrequired
Response
application/json
{
  "id": "string",
  "form_type": "questionnaire",
  "title": "string",
  "description": "string",
  "patient_title": "string",
  "patient_description": "string",
  "confirmation_message": "string",
  "snomed_code": "string",
  "fields": [
    { … }
  ],
  "patient_id": "string",
  "emis_file_record_at": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "appointment_id": 0,
  "write_to_record_status": "string"
}

List Form Responses

Request

Retrieves a list of all form responses.

Security
apiKeyAuth and practiceGroupId
Query
page_indexstring
page_sizestring
order_bystring
Enum"patient_first_name""patient_last_name""patient_full_name""form_title""form_type""created_at""updated_at"
statusstring
Enum"success""failed""not_written"
order_descendingboolean
patient_first_namestring
patient_last_namestring
patient_full_namestring
form_titlestring
form_typestring
patient_idstring
created_at[]Array of strings
servicestring
curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v2/form_responses?page_index=string&page_size=string&order_by=patient_first_name&status=success&order_descending=true&patient_first_name=string&patient_last_name=string&patient_full_name=string&form_title=string&form_type=string&patient_id=string&created_at%5B%5D=string&service=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 or null^\d+$
data[].​patientobject or null
data[].​write_to_recordobject or null
data[].​created_atstring or null(date-time)
data[].​updated_atstring or null(date-time)
data[].​form_typestring or null
data[].​form_titlestring or null
data[].​servicestring or null
countnumberrequired
Response
application/json
{
  "data": [
    { … }
  ],
  "count": 0
}

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.

Booking - HCA

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

Operations