Skip to content
/Task

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

Update a taskDeprecated

Request

Updates a task using the provided parameters.

Security
apiKeyAuth and practiceGroupId
Path
idstringrequired
Bodyapplication/jsonrequired
statusstring
Enum"open""closed""in_progress"
prioritystring
Enum"lowest""low""medium""high""highest"
assignee_typestring or null
Enum"admin""admin_team"
assignee_idstring or null^\d+$
curl -i -X PATCH \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/tasks/{id}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE' \
  -d '{
    "status": "open",
    "priority": "lowest",
    "assignee_type": "admin",
    "assignee_id": "string"
  }'

Responses

Ok

Bodyapplication/json
dataobjectrequired
data.​idstring^\d+$required
Response
application/json
{
  "data": {
    "id": "string"
  }
}

Get TaskDeprecated

Request

Retrieve task information for the given ID.

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

Responses

Ok

Bodyapplication/json
idstring^\d+$required
type_labelstringrequired
statusstringrequired
Enum"open""closed""in_progress"
detailsstring or null
categorystringrequired
patientobjectrequired
patient.​idstring^\d+$required
patient.​uidstring or null
patient.​ehr_partner_idstring or null
patient.​emis_idstring or null
patient.​deceased_atstring or null(date-time)
patient.​dobstring or null(date-time)required
patient.​titlestring or null
patient.​first_namestring or null
patient.​last_namestring or null
patient.​sexstringrequired
Enum"unspecified""male""female""other"
patient.​nhs_numberstring or null
patient.​emailstring or null
patient.​mobilestring or null
patient.​last_sync_atstring or null(date-time)
patient.​full_namestringrequired
patient.​contact_emailsArray of strings or nullrequired
patient.​registered_practitioner_namestring or nullrequired
patient.​notesstring or nullrequired
patient.​membership_scheme_namesArray of strings or nullrequired
patient.​addressobjectrequired
patient.​address.​line1string or null
patient.​address.​line2string or null
patient.​address.​line3string or null
patient.​address.​townstringrequired
patient.​address.​countystring or null
patient.​address.​countrystringrequired
patient.​address.​postcodestringrequired
patient.​verification_credentials_listArray of strings

An array of unique emails and mobile numbers from the verification credentials associated with the patients practice group, Only applicable for practices using the JS booking flow and marked as private

form_responseobject
appointmentobject
communicationobject
noteobject
assignee_idstring or null
assignee_typestring
assignee_namestring or null
prioritystringrequired
Enum"lowest""low""medium""high""highest"
created_atstringrequired
titlestringrequired
title_sub_textstringrequired
namestringrequired
taskable_typestringrequired
triggered_byobject or null
system_alert_detailsobject or null
form_response_idstring or number or null
One of:
string^\d+$
communication_idstring or number or null
One of:
string^\d+$
appointment_idstring or number or null
One of:
string^\d+$
note_idstring or number or null
One of:
string^\d+$
Response
application/json
{
  "id": "string",
  "type_label": "string",
  "status": "open",
  "details": "string",
  "category": "string",
  "patient": {
    "id": "string",
    "uid": "string",
    "ehr_partner_id": "string",
    "emis_id": "string",
    "deceased_at": "2019-08-24T14:15:22Z",
    "dob": "2019-08-24T14:15:22Z",
    "title": "string",
    "first_name": "string",
    "last_name": "string",
    "sex": "unspecified",
    "nhs_number": "string",
    "email": "string",
    "mobile": "string",
    "last_sync_at": "2019-08-24T14:15:22Z",
    "full_name": "string",
    "contact_emails": [ … ],
    "registered_practitioner_name": "string",
    "notes": "string",
    "membership_scheme_names": [ … ],
    "address": { … },
    "verification_credentials_list": [ … ]
  },
  "form_response": {
    "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",
    "title": "string",
    "submitted_at": "string",
    "form_questions_responses": [ … ],
    "form": { … },
    "write_to_record_status": "string"
  },
  "appointment": {
    "id": "string",
    "location_id": "string",
    "start_time": "2019-08-24T14:15:22Z",
    "reserved_until": "2019-08-24T14:15:22Z",
    "booking_confirmed_at": "2019-08-24T14:15:22Z",
    "can_be_cancelled": false,
    "can_be_rescheduled": false,
    "cancellation_policy_hours": 0,
    "appointment_template_name": "string",
    "cancelled_at": "2019-08-24T14:15:22Z",
    "confirmed_at": "2019-08-24T14:15:22Z",
    "appointment_source": "string",
    "video": false,
    "in_person": false,
    "telephone": false,
    "location_name": "string",
    "service": "string",
    "source": "string",
    "status": "string",
    "appointment_type_id": "string",
    "duration": 0,
    "patient_uid": "string",
    "practitioner_id": "string",
    "created_at": "string",
    "reason": "string",
    "practitioner_name": "string",
    "communication_method": "string",
    "video_url": "string",
    "rescheduled_at": "string"
  },
  "communication": {
    "id": "string",
    "content": "string",
    "contact_method": "email",
    "write_to_record_timestamp": "string",
    "write_to_record_error": "string",
    "notification": { … }
  },
  "note": {
    "id": 0,
    "description": "string",
    "admin": { … },
    "practice_group_id": 0,
    "archived_at": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "assignee_id": "string",
  "assignee_type": "string",
  "assignee_name": "string",
  "priority": "lowest",
  "created_at": "string",
  "title": "string",
  "title_sub_text": "string",
  "name": "string",
  "taskable_type": "string",
  "triggered_by": {
    "id": "string",
    "type": "Admin",
    "name": "string"
  },
  "system_alert_details": {
    "title": "string",
    "message": "string",
    "sub_title": "string",
    "action": "string"
  },
  "form_response_id": "string",
  "communication_id": "string",
  "appointment_id": "string",
  "note_id": "string"
}

List TasksDeprecated

Request

Retrieves a list of all tasks for a practice group.

Security
apiKeyAuth and practiceGroupId
Query
page_indexinteger
page_sizeinteger
assignee_id[]Array of strings
assignee_type[]Array of strings
Items Enum"Admin""AdminTeam""Unassigned"
status[]Array of strings
Items Enum"open""closed""in_progress"
priority[]Array of strings
Items Enum"lowest""low""medium""high""highest"
order_by[]Array of strings
Items Enum"created_at""priority"
order_descending[]Array of strings
curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v2/tasks?page_index=0&page_size=0&assignee_id%5B%5D=string&assignee_type%5B%5D=Admin&status%5B%5D=open&priority%5B%5D=lowest&order_by%5B%5D=created_at&order_descending%5B%5D=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[].​type_labelstringrequired
data[].​statusstringrequired
Enum"open""closed""in_progress"
data[].​detailsstring or null
data[].​categorystringrequired
data[].​patientobjectrequired
data[].​patient.​idstring^\d+$required
data[].​patient.​uidstring or null
data[].​patient.​ehr_partner_idstring or null
data[].​patient.​emis_idstring or null
data[].​patient.​deceased_atstring or null(date-time)
data[].​patient.​dobstring or null(date-time)required
data[].​patient.​titlestring or null
data[].​patient.​first_namestring or null
data[].​patient.​last_namestring or null
data[].​patient.​sexstringrequired
Enum"unspecified""male""female""other"
data[].​patient.​nhs_numberstring or null
data[].​patient.​emailstring or null
data[].​patient.​mobilestring or null
data[].​patient.​last_sync_atstring or null(date-time)
data[].​patient.​full_namestringrequired
data[].​patient.​contact_emailsArray of strings or nullrequired
data[].​patient.​registered_practitioner_namestring or nullrequired
data[].​patient.​notesstring or nullrequired
data[].​patient.​membership_scheme_namesArray of strings or nullrequired
data[].​patient.​addressobjectrequired
data[].​patient.​address.​line1string or null
data[].​patient.​address.​line2string or null
data[].​patient.​address.​line3string or null
data[].​patient.​address.​townstringrequired
data[].​patient.​address.​countystring or null
data[].​patient.​address.​countrystringrequired
data[].​patient.​address.​postcodestringrequired
data[].​patient.​verification_credentials_listArray of strings

An array of unique emails and mobile numbers from the verification credentials associated with the patients practice group, Only applicable for practices using the JS booking flow and marked as private

data[].​form_responseobject
data[].​appointmentobject
data[].​communicationobject
data[].​noteobject
data[].​assignee_idstring or null
data[].​assignee_typestring
data[].​assignee_namestring or null
data[].​prioritystringrequired
Enum"lowest""low""medium""high""highest"
data[].​created_atstringrequired
data[].​titlestringrequired
data[].​title_sub_textstringrequired
countnumberrequired
Response
application/json
{
  "data": [
    { … }
  ],
  "count": 0
}

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

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