Skip to content
API Reference
/
/
Get Patient Billing Info

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

Register a Patient

Request

Create or update a patient based on the data sent. If a patient with matching NHS number and DOB exists for the practice group, it will be updated. Otherwise, a new patient record is created.

Unlike Register Patient via PDS, this endpoint does not perform a Spine lookup — you provide the full patient demographics directly. Use this when you already hold the patient's details and do not need PDS tracing.

Security
apiKeyAuth and practiceGroupId
Bodyapplication/jsonrequired
One of:
ehr_partner_idstring
nhs_numberstring
dobstringnon-emptyrequired
first_namestringnon-emptyrequired
last_namestringnon-emptyrequired
sexstring
Enum"Not known""Not specified""Male""Female""Other"
titlestring
One of:
string
Enum"Baron""Baroness""Brigadier""Count""Colonel""Countess""Captain""Dame""The Dowager Viscountess""Dr"
landlinestring
address_line_1string
address_line_2string
address_line_3string
countrystring
postcodestring
townstring
countystring
data_sourcestring
Default "emis"
Enum"hero""emis""pds""gha""systm_one"
callerstringnon-empty

[Internal use only] The name of the application calling the register endpoint

mobilestringnon-emptyrequired
emailstring
curl -i -X POST \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/patients/register \
  -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",
    "nhs_number": "string",
    "dob": "string",
    "first_name": "string",
    "last_name": "string",
    "sex": "Not known",
    "title": "Baron",
    "landline": "string",
    "address_line_1": "string",
    "address_line_2": "string",
    "address_line_3": "string",
    "country": "string",
    "postcode": "string",
    "town": "string",
    "county": "string",
    "data_source": "hero",
    "caller": "string",
    "mobile": "string",
    "email": "string"
  }'

Responses

Ok

Bodyapplication/json
patient_idstring^\d+$required
Response
application/json
{
  "patient_id": "string"
}

Get Patient Billing Info

Request

Retrieves billing information for the patient.

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

Responses

Ok

Bodyapplication/json
idstring^\d+$required
external_billing_idstringrequired
insuranceobjectrequired
insurance.​insurerstring or nullrequired
insurance.​membership_numberstring or nullrequired
insurance.​auth_codestring or nullrequired
billing_notestring or nullrequired
confidentialboolean or nullrequired
Response
application/json
{
  "id": "string",
  "external_billing_id": "string",
  "insurance": {
    "insurer": "string",
    "membership_number": "string",
    "auth_code": "string"
  },
  "billing_note": "string",
  "confidential": true
}

List Patient Payment Methods

Request

Retrieves payment methods for default stripe customer of patient.

Security
apiKeyAuth and practiceGroupId
Path
idstringrequired
curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/patients/{id}/payment_methods' \
  -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[].​idstringrequired
data[].​typestringrequired
data[].​brandstringrequired
data[].​last4stringrequired
data[].​checksobject
data[].​walletstring or null
data[].​countrystring or nullrequired
data[].​fundingstring or nullrequired
data[].​exp_yearnumber or nullrequired
data[].​networksobject
data[].​exp_monthnumber or nullrequired
data[].​display_brandstring or null
data[].​generated_fromstring or null
data[].​fingerprintstring or nullrequired
data[].​regulated_statusstring or nullrequired
data[].​three_d_secure_usageobject
countnumberrequired
Response
application/json
{
  "data": [
    { … }
  ],
  "count": 0
}

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