Skip to content
API Reference
/
/
Connect a Patient to EHR

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

List Candidates for the Patient on EHR

Request

Retrieve a list of candidates that can be matched against the patient on EHR

Security
apiKeyAuth and practiceGroupId
Path
idstringrequired
curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/patients/{id}/ehr/candidates' \
  -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[].​ehr_partner_idstring or null
data[].​emis_idstring or null
data[].​deceased_atstring or null(date-time)
data[].​dobstring or null(date-time)required
data[].​titlestring or null
Enum"Baron""Baroness""Brigadier""Count""Colonel""Countess""Captain""Dame""The Dowager Viscountess""Dr"
data[].​first_namestring or null
data[].​last_namestring or null
data[].​sexstring or null
Enum"Not known""Not specified""Male""Female""Other"
data[].​nhs_numberstring or null
data[].​emailstring or null
data[].​mobilestring or null
data[].​last_sync_atstring or null(date-time)
data[].​data_sourcestring or null
Enum"hero""emis""pds""gha""systm_one"
data[].​restrictedboolean
Default false
data[].​line_1string or null
data[].​line_2string or null
data[].​line_3string or null
data[].​townstring or null
data[].​countystring or null
data[].​postcodestring or null
data[].​hero_idstring or null^\d+$
data[].​hero_uidstring or null
data[].​identifiersArray of objectsrequired
data[].​identifiers[].​sourcestringrequired
Enum"nhs""gha""ehr_partner""hero"
data[].​identifiers[].​namestringrequired
Enum"nhs_number""gha_number""ehr_partner_id""hero_id""hero_uid"
data[].​identifiers[].​rolestringrequired
Enum"main""secondary"
data[].​identifiers[].​labelstringrequired
Enum"NHS""GHA""EMIS""Hero""Systm One"
data[].​identifiers[].​valuestringrequired
data[].​ehr_registeredboolean or nullrequired
countnumberrequired
Response
application/json
{
  "data": [
    { … }
  ],
  "count": 0
}

Connect a Patient to EHR

Request

Connect a patient to an EHR patient

Security
apiKeyAuth and practiceGroupId
Path
idstringrequired
Bodyapplication/jsonrequired
ehr_partner_idstringrequired
curl -i -X POST \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/patients/{id}/ehr/connect' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE' \
  -d '{
    "ehr_partner_id": "string"
  }'

Responses

Ok

Response
No content

Preview Patient Merging

Request

Return a preview of a merge between two patients hand provide a merge token

Security
apiKeyAuth and practiceGroupId
Path
idstringrequired
Bodyapplication/jsonrequired
patient_idstring^\d+$required
curl -i -X POST \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/patients/{id}/merge/preview' \
  -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": "string"
  }'

Responses

Ok

Bodyapplication/json
main_patientobjectrequired
main_patient.​idstring^\d+$required
main_patient.​uidstring or null
main_patient.​emis_idstring or null
main_patient.​ehr_partner_idstring or null
main_patient.​dobstring or null(date-time)required
main_patient.​deceased_atstring or null(date-time)
main_patient.​titlestring or null
Enum"Baron""Baroness""Brigadier""Count""Colonel""Countess""Captain""Dame""The Dowager Viscountess""Dr"
main_patient.​first_namestring or null
main_patient.​last_namestring or null
main_patient.​sexstring or null
Enum"Not known""Not specified""Male""Female""Other"
main_patient.​nhs_numberstring or null
main_patient.​emailstring or null
main_patient.​emailsArray of strings or null
main_patient.​mobilestring or null
main_patient.​last_sync_atstring or null(date-time)
main_patient.​address_line_1string or null
main_patient.​address_line_2string or null
main_patient.​address_line_3string or null
main_patient.​countrystring or null
main_patient.​postcodestring or null
main_patient.​townstring or null
main_patient.​countystring or null
main_patient.​notesstring or null
main_patient.​verification_credentialsArray of strings or null
main_patient.​data_sourcestringrequired
Enum"hero""emis""pds""gha""systm_one"
main_patient.​restrictedboolean
Default false
main_patient.​sex_changed_atstring or null(date-time)
main_patient.​statusstringrequired
Enum"archived""unarchived"
main_patient.​ods_codestring or null
main_patient.​identifiersArray of objectsrequired
main_patient.​identifiers[].​sourcestringrequired
Enum"nhs""gha""ehr_partner""hero"
main_patient.​identifiers[].​namestringrequired
Enum"nhs_number""gha_number""ehr_partner_id""hero_id""hero_uid"
main_patient.​identifiers[].​rolestringrequired
Enum"main""secondary"
main_patient.​identifiers[].​labelstringrequired
Enum"NHS""GHA""EMIS""Hero""Systm One"
main_patient.​identifiers[].​valuestringrequired
main_patient.​ehr_registeredboolean or nullrequired
incoming_patientobjectrequired
incoming_patient.​idstring^\d+$required
incoming_patient.​uidstring or null
incoming_patient.​emis_idstring or null
incoming_patient.​ehr_partner_idstring or null
incoming_patient.​dobstring or null(date-time)required
incoming_patient.​deceased_atstring or null(date-time)
incoming_patient.​titlestring or null
Enum"Baron""Baroness""Brigadier""Count""Colonel""Countess""Captain""Dame""The Dowager Viscountess""Dr"
incoming_patient.​first_namestring or null
incoming_patient.​last_namestring or null
incoming_patient.​sexstring or null
Enum"Not known""Not specified""Male""Female""Other"
incoming_patient.​nhs_numberstring or null
incoming_patient.​emailstring or null
incoming_patient.​emailsArray of strings or null
incoming_patient.​mobilestring or null
incoming_patient.​last_sync_atstring or null(date-time)
incoming_patient.​address_line_1string or null
incoming_patient.​address_line_2string or null
incoming_patient.​address_line_3string or null
incoming_patient.​countrystring or null
incoming_patient.​postcodestring or null
incoming_patient.​townstring or null
incoming_patient.​countystring or null
incoming_patient.​notesstring or null
incoming_patient.​verification_credentialsArray of strings or null
incoming_patient.​data_sourcestringrequired
Enum"hero""emis""pds""gha""systm_one"
incoming_patient.​restrictedboolean
Default false
incoming_patient.​sex_changed_atstring or null(date-time)
incoming_patient.​statusstringrequired
Enum"archived""unarchived"
incoming_patient.​ods_codestring or null
incoming_patient.​identifiersArray of objectsrequired
incoming_patient.​identifiers[].​sourcestringrequired
Enum"nhs""gha""ehr_partner""hero"
incoming_patient.​identifiers[].​namestringrequired
Enum"nhs_number""gha_number""ehr_partner_id""hero_id""hero_uid"
incoming_patient.​identifiers[].​rolestringrequired
Enum"main""secondary"
incoming_patient.​identifiers[].​labelstringrequired
Enum"NHS""GHA""EMIS""Hero""Systm One"
incoming_patient.​identifiers[].​valuestringrequired
incoming_patient.​ehr_registeredboolean or nullrequired
result_patientobjectrequired
result_patient.​idstring^\d+$required
result_patient.​uidstring or null
result_patient.​emis_idstring or null
result_patient.​ehr_partner_idstring or null
result_patient.​dobstring or null(date-time)required
result_patient.​deceased_atstring or null(date-time)
result_patient.​titlestring or null
Enum"Baron""Baroness""Brigadier""Count""Colonel""Countess""Captain""Dame""The Dowager Viscountess""Dr"
result_patient.​first_namestring or null
result_patient.​last_namestring or null
result_patient.​sexstring or null
Enum"Not known""Not specified""Male""Female""Other"
result_patient.​nhs_numberstring or null
result_patient.​emailstring or null
result_patient.​emailsArray of strings or null
result_patient.​mobilestring or null
result_patient.​last_sync_atstring or null(date-time)
result_patient.​address_line_1string or null
result_patient.​address_line_2string or null
result_patient.​address_line_3string or null
result_patient.​countrystring or null
result_patient.​postcodestring or null
result_patient.​townstring or null
result_patient.​countystring or null
result_patient.​notesstring or null
result_patient.​verification_credentialsArray of strings or null
result_patient.​data_sourcestringrequired
Enum"hero""emis""pds""gha""systm_one"
result_patient.​restrictedboolean
Default false
result_patient.​sex_changed_atstring or null(date-time)
result_patient.​statusstringrequired
Enum"archived""unarchived"
result_patient.​ods_codestring or null
result_patient.​identifiersArray of objectsrequired
result_patient.​identifiers[].​sourcestringrequired
Enum"nhs""gha""ehr_partner""hero"
result_patient.​identifiers[].​namestringrequired
Enum"nhs_number""gha_number""ehr_partner_id""hero_id""hero_uid"
result_patient.​identifiers[].​rolestringrequired
Enum"main""secondary"
result_patient.​identifiers[].​labelstringrequired
Enum"NHS""GHA""EMIS""Hero""Systm One"
result_patient.​identifiers[].​valuestringrequired
result_patient.​ehr_registeredboolean or nullrequired
merge_tokenstringrequired
Response
application/json
{
  "main_patient": {
    "id": "string",
    "uid": "string",
    "emis_id": "string",
    "ehr_partner_id": "string",
    "dob": "2019-08-24T14:15:22Z",
    "deceased_at": "2019-08-24T14:15:22Z",
    "title": "Baron",
    "first_name": "string",
    "last_name": "string",
    "sex": "Not known",
    "nhs_number": "string",
    "email": "string",
    "emails": [ … ],
    "mobile": "string",
    "last_sync_at": "2019-08-24T14:15:22Z",
    "address_line_1": "string",
    "address_line_2": "string",
    "address_line_3": "string",
    "country": "string",
    "postcode": "string",
    "town": "string",
    "county": "string",
    "notes": "string",
    "verification_credentials": [ … ],
    "data_source": "hero",
    "restricted": false,
    "sex_changed_at": "2019-08-24T14:15:22Z",
    "status": "archived",
    "ods_code": "string",
    "identifiers": [ … ],
    "ehr_registered": true
  },
  "incoming_patient": {
    "id": "string",
    "uid": "string",
    "emis_id": "string",
    "ehr_partner_id": "string",
    "dob": "2019-08-24T14:15:22Z",
    "deceased_at": "2019-08-24T14:15:22Z",
    "title": "Baron",
    "first_name": "string",
    "last_name": "string",
    "sex": "Not known",
    "nhs_number": "string",
    "email": "string",
    "emails": [ … ],
    "mobile": "string",
    "last_sync_at": "2019-08-24T14:15:22Z",
    "address_line_1": "string",
    "address_line_2": "string",
    "address_line_3": "string",
    "country": "string",
    "postcode": "string",
    "town": "string",
    "county": "string",
    "notes": "string",
    "verification_credentials": [ … ],
    "data_source": "hero",
    "restricted": false,
    "sex_changed_at": "2019-08-24T14:15:22Z",
    "status": "archived",
    "ods_code": "string",
    "identifiers": [ … ],
    "ehr_registered": true
  },
  "result_patient": {
    "id": "string",
    "uid": "string",
    "emis_id": "string",
    "ehr_partner_id": "string",
    "dob": "2019-08-24T14:15:22Z",
    "deceased_at": "2019-08-24T14:15:22Z",
    "title": "Baron",
    "first_name": "string",
    "last_name": "string",
    "sex": "Not known",
    "nhs_number": "string",
    "email": "string",
    "emails": [ … ],
    "mobile": "string",
    "last_sync_at": "2019-08-24T14:15:22Z",
    "address_line_1": "string",
    "address_line_2": "string",
    "address_line_3": "string",
    "country": "string",
    "postcode": "string",
    "town": "string",
    "county": "string",
    "notes": "string",
    "verification_credentials": [ … ],
    "data_source": "hero",
    "restricted": false,
    "sex_changed_at": "2019-08-24T14:15:22Z",
    "status": "archived",
    "ods_code": "string",
    "identifiers": [ … ],
    "ehr_registered": true
  },
  "merge_token": "string"
}

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