Skip to content
API Reference
/
/
Create Invoice

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

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

Get Default Customer

Request

Retrieves the default Stripe customer for a patient.

Security
apiKeyAuth and practiceGroupId
Query
patient_idstringrequired

The unique identifier of the patient

curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/invoicing/customers/default?patient_id=string' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Ok

Bodyapplication/json
idstringrequired
namestringrequired
emailstring(email)
phonestring
sourcesArray of objects
Response
application/json
{
  "id": "string",
  "name": "string",
  "email": "user@example.com",
  "phone": "string",
  "sources": [
    { … }
  ]
}

Create Invoice

Request

Creates a new invoice for a patient.

The issuer_id parameter is required and must be the Admin ID of the person issuing the invoice.

Either patient_id or appointment_id must be provided. If appointment_id is provided, the patient will be derived from the appointment.

Use the List Products endpoint to retrieve available invoice items.

Security
apiKeyAuth and practiceGroupId
Bodyapplication/jsonrequired
issuer_idstringrequired
patient_idstring
appointment_idstring
practitioner_idstring
service_datestring
customer_stripe_idstring
set_default_customerboolean
due_datestring
collection_methodstring
Enum"request_payment""charge_automatically"
payment_sourcestring
insurerstring
authentication_codestring
membership_numberstring
diagnosisstring
memostring
footerstring
confidentialboolean
modestring
Default "draft"
Enum"draft""finalize"
couponsArray of objects
invoice_items_attributesArray of objects
curl -i -X POST \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/invoicing/invoices \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE' \
  -d '{
    "issuer_id": "string",
    "patient_id": "string",
    "appointment_id": "string",
    "practitioner_id": "string",
    "service_date": "string",
    "customer_stripe_id": "string",
    "set_default_customer": true,
    "due_date": "string",
    "collection_method": "request_payment",
    "payment_source": "string",
    "insurer": "string",
    "authentication_code": "string",
    "membership_number": "string",
    "diagnosis": "string",
    "memo": "string",
    "footer": "string",
    "confidential": true,
    "mode": "draft",
    "coupons": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "invoice_items_attributes": [
      {
        "price": "string",
        "product": "string",
        "description": "string",
        "quantity": 0,
        "unit_amount": 0,
        "unit_amount_in_pounds": 0,
        "create": true,
        "stripe_id": "string"
      }
    ]
  }'

Responses

Invoice created successfully

Bodyapplication/json
idstring or null
stripe_idstringrequired
statusstring
subtotalnumber
amount_duenumber
customer_idstring or null
patient_record_idstring or null
appointment_idstring or null
created_atstring
updated_atstring
Response
application/json
{
  "id": "string",
  "stripe_id": "string",
  "status": "string",
  "subtotal": 0,
  "amount_due": 0,
  "customer_id": "string",
  "patient_record_id": "string",
  "appointment_id": "string",
  "created_at": "string",
  "updated_at": "string"
}

Update Invoice

Request

Updates an existing invoice.

The issuer_id parameter is required and must be the Admin ID of the person updating the invoice.

For draft invoices, all fields can be updated. For finalized invoices, only metadata fields (memo, footer, coupons) can be updated.

Security
apiKeyAuth and practiceGroupId
Path
idstringrequired

The invoice ID

Bodyapplication/jsonrequired
issuer_idstringrequired
appointment_idstring
practitioner_idstring
service_datestring
customer_stripe_idstring
set_default_customerboolean
due_datestring
collection_methodstring
Enum"request_payment""charge_automatically"
payment_sourcestring
insurerstring
authentication_codestring
membership_numberstring
diagnosisstring
memostring
footerstring
confidentialboolean
modestring
Enum"draft""finalize"
couponsArray of objects
invoice_items_attributesArray of objects
curl -i -X PATCH \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/invoicing/invoices/{id}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE' \
  -d '{
    "issuer_id": "string",
    "appointment_id": "string",
    "practitioner_id": "string",
    "service_date": "string",
    "customer_stripe_id": "string",
    "set_default_customer": true,
    "due_date": "string",
    "collection_method": "request_payment",
    "payment_source": "string",
    "insurer": "string",
    "authentication_code": "string",
    "membership_number": "string",
    "diagnosis": "string",
    "memo": "string",
    "footer": "string",
    "confidential": true,
    "mode": "draft",
    "coupons": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "invoice_items_attributes": [
      {
        "price": "string",
        "product": "string",
        "description": "string",
        "quantity": 0,
        "unit_amount": 0,
        "unit_amount_in_pounds": 0,
        "create": true,
        "stripe_id": "string"
      }
    ]
  }'

Responses

Invoice updated successfully

Bodyapplication/json
idstring or null
stripe_idstringrequired
statusstring
subtotalnumber
amount_duenumber
customer_idstring or null
patient_record_idstring or null
appointment_idstring or null
created_atstring
updated_atstring
Response
application/json
{
  "id": "string",
  "stripe_id": "string",
  "status": "string",
  "subtotal": 0,
  "amount_due": 0,
  "customer_id": "string",
  "patient_record_id": "string",
  "appointment_id": "string",
  "created_at": "string",
  "updated_at": "string"
}

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