Skip to content
API Reference
/
/
Send a Message

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

Get Message

Request

Retrieves a message by its ID.

Security
apiKeyAuth and practiceGroupId
Path
idstringrequired
curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/messages/{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
patientobjectrequired
patient.​idstring^\d+$required
patient.​titlestring or nullrequired
Enum"Baron""Baroness""Brigadier""Count""Colonel""Countess""Captain""Dame""The Dowager Viscountess""Dr"
patient.​first_namestringrequired
patient.​last_namestringrequired
write_to_recordobjectrequired
write_to_record.​write_to_record_atstring or null(date-time)required
write_to_record.​statusstring or nullrequired
write_to_record.​failure_reasonstring or nullrequired
write_to_record.​snomed_codestring or nullrequired
short_linkobject or nullrequired
short_link.​idstring or null^\d+$
short_link.​typestring or null
short_link.​namestring or null
short_link.​statusstring or null
campaignobject or nullrequired
campaign.​idstring or null^\d+$
campaign.​namestring or null
created_atstring or null(date-time)required
sent_atstring or null(date-time)required
scheduled_atstring or null(date-time)required
statusstringrequired
Enum"delivered""declined""sent""pending""retry""fatal"
sent_by_adminobjectrequired
sent_by_admin.​idstring^\d+$required
sent_by_admin.​first_namestringrequired
sent_by_admin.​last_namestringrequired
recipient_contact_detailstringrequired
message_typestringrequired
messagestring or nullrequired
attachmentsArray of objects
Response
application/json
{
  "id": "string",
  "patient": {
    "id": "string",
    "title": "Baron",
    "first_name": "string",
    "last_name": "string"
  },
  "write_to_record": {
    "write_to_record_at": "2019-08-24T14:15:22Z",
    "status": "string",
    "failure_reason": "string",
    "snomed_code": "string"
  },
  "short_link": {
    "id": "string",
    "type": "string",
    "name": "string",
    "status": "string"
  },
  "campaign": {
    "id": "string",
    "name": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "sent_at": "2019-08-24T14:15:22Z",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "status": "delivered",
  "sent_by_admin": {
    "id": "string",
    "first_name": "string",
    "last_name": "string"
  },
  "recipient_contact_detail": "string",
  "message_type": "string",
  "message": "string",
  "attachments": [
    { … }
  ]
}

Send a Message

Request

Send a message to a patient via SMS, email, NHS App, or as a Hero-only audit record.

Message types:

  • sms — Sent via the practice's configured SMS provider (e.g. Firetext)
  • email — Sent via Hero's email service (AWS SES)
  • nhs_app — Delivered through the NHS App
  • hero — Not delivered to the patient; used as an audit log for messages sent externally

Set write_to_record: true to persist the message in the patient's EHR (EMIS/TPP) after clinician approval. Use auto_write_to_record: true (if permitted by your API key scopes) to skip the approval step.

Security
apiKeyAuth and practiceGroupId
Bodyapplication/jsonrequired
patient_idstring^\d+$required

The Hero patient the message relates to

message_typestringrequired

Defines if the message will be sent on via Hero's comms tools, and by what method

Enum"hero""sms""email""nhs_app"
message_stringstringnon-emptyrequired

Message content to be sent from Hero

recipient_contact_detailstring

Where the message will be sent (e.g. patient@email.com or +44 79000000000). If no value is provided a default will be picked from the patients record (for that contact method, SMS/Email).

fallback_contact_detailstring
fallback_message_typestring
Enum"sms""email"
write_to_recordboolean

Flags if the message should be written to the EHR record post-approval

Default false
encryptedboolean or string

Flags if the message should be encrypted

Default false
One of:

Flags if the message should be encrypted

boolean
Default false
snomed_codestring

SNOMED code to be attached to the EHR record entry. Default value applied if not passed and write_to_record is true

snomed_termstring

SNOMED term to be attached to the EHR record entry. Default value applied if not passed and write_to_record is true

auto_write_to_recordboolean

Param only considered if API key permissions allow. Automatically writes to the EHR record without requiring Hero admin approval

Default false
task_idstring

Task ID to be attached to a task

attachment_uuidstringnon-empty
short_link_idstringnon-empty
assignee_idnumber

Optional. ID of the Admin or AdminTeam assigned to the message

assignee_typestring

Type of the assignee, either Admin or AdminTeam, assigned to the message

send_atstring(date-time)

Specifies the scheduled date and time to send the message.

curl -i -X POST \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/messages/send \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE' \
  -d '{
    "patient_id": "1234",
    "message_type": "sms",
    "message_string": "Dear patient, your appointment is confirmed for 15 March at 09:30.",
    "recipient_contact_detail": "+447700900123",
    "write_to_record": true
  }'

Responses

Ok

Bodyapplication/json
message_idstringrequired
contentstringrequired
created_atstringrequired
snomed_codestring or null
write_to_recordbooleanrequired
auth_tokenstring or null
confirm_write_to_record_urlstring or null
submitted_bystring or null
send_atstring or null(date-time)
Response
application/json
{
  "message_id": "string",
  "content": "string",
  "created_at": "string",
  "snomed_code": "string",
  "write_to_record": true,
  "auth_token": "string",
  "confirm_write_to_record_url": "string",
  "submitted_by": "string",
  "send_at": "2019-08-24T14:15:22Z"
}

Get Message Status

Request

Retrieve message write to record and send status

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

Responses

Ok

Bodyapplication/json
idstringrequired
scheduled_send_atstring or null(date-time)required
write_to_recordbooleanrequired
statusobjectrequired
status.​write_to_record_atstring or null(date-time)required
status.​sent_atstring or null(date-time)required
status.​responsestringrequired
Enum"delivered""declined""sent""pending""retry""fatal"
status.​failure_reasonstring or nullrequired
errorsobjectrequired
errors.​write_to_recordstring or nullrequired
errors.​sendstring or nullrequired
Response
application/json
{
  "id": "string",
  "scheduled_send_at": "2019-08-24T14:15:22Z",
  "write_to_record": true,
  "status": {
    "write_to_record_at": "2019-08-24T14:15:22Z",
    "sent_at": "2019-08-24T14:15:22Z",
    "response": "delivered",
    "failure_reason": "string"
  },
  "errors": {
    "write_to_record": "string",
    "send": "string"
  }
}

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