# Hero Health Public API

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.

Version: 1.0.0

## Servers

Staging
```
https://api.staging.htech.app
```

Production
```
https://api.herohealth.net
```

## Security

### apiKeyAuth

Your Hero Health API key. Request one from Hero support with the scopes you need (messaging, booking, booking links).

Type: apiKey
In: header
Name: x-api-key

### practiceGroupId

The ID of the practice group you are making requests for. Provided by Hero during onboarding.

Type: apiKey
In: header
Name: x-practice-group-id

## Download OpenAPI description

[Hero Health Public API](https://developer.herohealth.net/_bundle/apis/public-api/openapi.yaml)

## Appointments

Create appointment reservations, confirm bookings, cancel, and reschedule. Query available slots and appointment types filtered by location, practitioner, and appointment type.

### Get an Appointment

 - [GET /v1/appointments/{id}](https://developer.herohealth.net/apis/public-api/openapi/appointments/getappointment.md): Retrieves an appointment by its ID.

### Get Appointment Status

 - [GET /v1/appointments/{id}/status](https://developer.herohealth.net/apis/public-api/openapi/appointments/getappointmentstatus.md): Retrieves the status of an appointment by its ID, including the derived booking status and EHR partner status.

### Create an Appointment

 - [POST /v1/appointments](https://developer.herohealth.net/apis/public-api/openapi/appointments/createappointment.md): Create an appointment reservation for a patient. The appointment is held in a reserved state until confirmed via the Book Appointment endpoint.

Flow: List Slots → Create Appointment (reserve) → Book Appointment (confirm).

If the reservation is not confirmed within the hold period, it will be automatically released.

The optional booking_mechanism field defaults to hero_confirmed. ehr_confirmed appointments must be managed via the v2 endpoints; v1 supports hero_confirmed only.

### List Appointment Types

 - [GET /v1/appointment_types](https://developer.herohealth.net/apis/public-api/openapi/appointments/listappointmenttypes.md): Retrieves a list of all appointment types configured for the requesting practice group.

### Get Booking Link

 - [GET /v1/booking_links/{id}](https://developer.herohealth.net/apis/public-api/openapi/appointments/getbookinglink.md): Get a booking link and its fields.

### Count Bookable Slots

 - [GET /v1/slots/count](https://developer.herohealth.net/apis/public-api/openapi/appointments/countslots.md): Count of all bookable slots for the requesting practice group.

### Get Bookable Slot

 - [GET /v1/slots/{id}](https://developer.herohealth.net/apis/public-api/openapi/appointments/getslot.md): Retrieves a single bookable slot by its ID for the requesting practice group.

### List Bookable Slots

 - [GET /v1/slots](https://developer.herohealth.net/apis/public-api/openapi/appointments/listslots.md): Retrieve available bookable slots for the practice group. Filter by location, practitioner, appointment type, and date range.

Typical flow: List Appointment Types → List Slots (filtered) → Create Appointment → Book Appointment.

Results are paginated. Use start_date and end_date query parameters to narrow the date window.

### Check slot availability

 - [POST /v1/slots/availability](https://developer.herohealth.net/apis/public-api/openapi/appointments/checkslotsavailability.md): Check whether a specific slot is still available for booking. Call this immediately before creating an appointment to avoid reservation conflicts.

### List Appointments

 - [GET /v2/appointments](https://developer.herohealth.net/apis/public-api/openapi/appointments/listappointments.md): Retrieves a list of all appointments.

### Book an Appointment

 - [PATCH /v2/appointments/{id}/book](https://developer.herohealth.net/apis/public-api/openapi/appointments/bookappointmentv2.md): Submits a previously reserved appointment for booking. Returns immediately with
status "pending"; the booking is confirmed asynchronously. Poll Get Appointment
Status for the outcome.

Only appointments reserved with booking_mechanism: ehr_confirmed can be booked here; hero_confirmed appointments must be booked via the v1 endpoint.

### Cancel an Appointment

 - [PATCH /v2/appointments/{id}/cancel](https://developer.herohealth.net/apis/public-api/openapi/appointments/cancelappointmentv2.md): Cancels a confirmed appointment. Returns immediately with status "cancelling";
the cancellation is confirmed asynchronously. Poll Get Appointment Status for
the outcome.

### Reschedule Appointment

 - [PATCH /v2/appointments/{id}/reschedule](https://developer.herohealth.net/apis/public-api/openapi/appointments/rescheduleappointmentv2.md): Asynchronously reschedules an EHR-confirmed appointment to a new slot (book-new then cancel-old). Returns immediately with a rescheduling status; poll the status endpoint for the outcome.

### Edit an Appointment reservation

 - [PUT /v2/appointments/{id}](https://developer.herohealth.net/apis/public-api/openapi/appointments/editappointmentv2.md): Updates an unconfirmed reservation in place - slot, practitioner, reason,
patient proxy - and re-stamps the reservation hold, returning the fresh
reserved_until. Only appointments in the reserved state can be edited;
use Reschedule for confirmed appointments. Works for both booking
mechanisms - a reservation has not touched the EHR yet. The location
and appointment type cannot change - release the reservation and
re-reserve to move site or change type.

### List Automated messages

 - [GET /v2/automated_messages](https://developer.herohealth.net/apis/public-api/openapi/appointments/listautomatedmessages.md): Retrieves a list of automated appointment messages.

### List Booking links

 - [GET /v2/bookinglinks](https://developer.herohealth.net/apis/public-api/openapi/appointments/listbookinglinks.md): Retrieves a list of shortlinks filtered by 'booking' link type and version 2.

### Edit an Appointment (deprecated)

 - [PUT /v1/appointments/{id}](https://developer.herohealth.net/apis/public-api/openapi/appointments/editappointment.md): Deprecated: new integrations should use PUT /v2/appointments/{id} (editAppointmentV2) instead. This endpoint remains available for existing hero_confirmed integrations.

Edit a non-confirmed appointment

### Book an Appointment (deprecated)

 - [PATCH /v1/appointments/{id}/book](https://developer.herohealth.net/apis/public-api/openapi/appointments/bookappointment.md): Deprecated: new integrations should use PATCH /v2/appointments/{id}/book (bookAppointmentV2) instead. This endpoint remains available for existing hero_confirmed integrations.

Confirm a previously reserved appointment. This transitions the appointment from reserved to booked status and triggers any configured notifications (e.g. patient confirmation SMS).

The appointment must have been created via the Create Appointment endpoint first. Appointments reserved with booking_mechanism: ehr_confirmed must be booked via the v2 endpoint.

### Cancel an Appointment (deprecated)

 - [PATCH /v1/appointments/{id}/cancel](https://developer.herohealth.net/apis/public-api/openapi/appointments/cancelappointment.md): Deprecated: new integrations should use PATCH /v2/appointments/{id}/cancel (cancelAppointmentV2) instead. This endpoint remains available for existing hero_confirmed integrations.

Cancel a booked or reserved appointment. The slot will be released and made available for other bookings.

### Reschedule an Appointment (deprecated)

 - [PATCH /v1/appointments/{id}/reschedule](https://developer.herohealth.net/apis/public-api/openapi/appointments/rescheduleappointment.md): Deprecated: new integrations should use PATCH /v2/appointments/{id}/reschedule (rescheduleAppointmentV2) instead. This endpoint remains available for existing hero_confirmed integrations.

Reschedule a confirmed appointment

## Practitioners

List, retrieve, update, and archive practitioners within a practice group.

### List Practitioners

 - [GET /v1/practitioners](https://developer.herohealth.net/apis/public-api/openapi/practitioners/listpractitioners.md): Retrieves a list of practitioners configured for online booking on Hero Health.

### Get a Practitioner

 - [GET /v1/practitioners/{id}](https://developer.herohealth.net/apis/public-api/openapi/practitioners/getpractitioner.md): Retrieves a single practitioner by ID.

### Update a Practitioner

 - [PATCH /v1/practitioners/{id}](https://developer.herohealth.net/apis/public-api/openapi/practitioners/updatepractitioner.md): Updates a practitioner's identity and contact fields.

### Archive a Practitioner

 - [DELETE /v1/practitioners/{id}](https://developer.herohealth.net/apis/public-api/openapi/practitioners/archivepractitioner.md): Archives a practitioner so they are no longer active.

## Locations

List, retrieve, create, update, and archive locations for a practice group.

### List Locations

 - [GET /v1/locations](https://developer.herohealth.net/apis/public-api/openapi/locations/listlocations.md): Retrieves a list of the locations configured for a practice group on Hero Health.

### Get a Location

 - [GET /v1/locations/{id}](https://developer.herohealth.net/apis/public-api/openapi/locations/getlocationbyid.md): Retrieve a single location by its ID.

### Update a Location

 - [PATCH /v1/locations/{id}](https://developer.herohealth.net/apis/public-api/openapi/locations/updatelocation.md): Update an existing location.

### Archive a Location

 - [DELETE /v1/locations/{id}](https://developer.herohealth.net/apis/public-api/openapi/locations/archivelocation.md): Archive a location. Archived locations are no longer visible to patients.

## Admin

Manage admin users, signatures, and preferences within a practice group.

### List Admins

 - [GET /v1/admins](https://developer.herohealth.net/apis/public-api/openapi/admin/listadmins.md): Retrieves a list of all admins.

### Update an Admin

 - [PATCH /v1/admins/{id}](https://developer.herohealth.net/apis/public-api/openapi/admin/updateadmin.md): Updates an admin using the provided parameters.

### Upsert Admin In-Context Signature

 - [POST /v1/admin/signature](https://developer.herohealth.net/apis/public-api/openapi/admin/upsertadminsignature.md): Insert or update a signature for Admin in context.

### Upsert Admin In-Context Preferences

 - [PATCH /v1/admin/preferences](https://developer.herohealth.net/apis/public-api/openapi/admin/upsertadminpreferences.md): Insert or update preferences for the given Admin.

### Get prescriber details

 - [GET /v1/admins/{id}/prescriber](https://developer.herohealth.net/apis/public-api/openapi/admin/getprescriber.md): Retrieves prescriber details for the admin.

### List Admin Teams

 - [GET /v1/admin_teams](https://developer.herohealth.net/apis/public-api/openapi/admin/listadminteams.md): Retrieves a list of all admin teams.

### Create an Admin Team

 - [POST /v1/admin_teams](https://developer.herohealth.net/apis/public-api/openapi/admin/createadminteam.md): Creates a new admin team with the specified name and admin members.

## Practice Group

Manage practice group settings, access tokens, and configuration. Use the access token endpoint to generate short-lived JWTs for Hero Elements.

### Create an Access Token

 - [POST /v1/access_token](https://developer.herohealth.net/apis/public-api/openapi/practice-group/createaccesstoken.md): Generate a short-lived Access Token (JWT) to authenticate Hero Health Elements (SDKs).

Important: This endpoint must only be called from your server — never from client-side code. The returned token expires after 30 minutes.

Use the returned access_token as the jwt-token attribute when rendering a Hero Element (React component or Web Component).

Admin attribution on the newly created token is resolved from:
  - x-admin-id on token generation (header)
  - the default-admin behaviour: falls back to the practice group's configured default admin when the header is not supplied.

### List Content Templates

 - [GET /v1/content-templates](https://developer.herohealth.net/apis/public-api/openapi/practice-group/listcontenttemplates.md): Retrieves a list of content templates available to the requesting practice group.

### Get Practice Group

 - [GET /v1/me](https://developer.herohealth.net/apis/public-api/openapi/practice-group/getpracticegroupbyid.md): Retrieves information regarding the authenticated Practice Group.

### Get Practice Group Capabilities

 - [GET /v1/me/capabilities](https://developer.herohealth.net/apis/public-api/openapi/practice-group/getcapabilities.md): Retrieves capabilities of the authenticated Practice Group.

### List Network Practices

 - [GET /v1/network](https://developer.herohealth.net/apis/public-api/openapi/practice-group/listnetworkpractices.md): List practice groups from the same network as the authenticated Practice Group.

### Get Practice Group SMS credit count

 - [GET /v1/me/sms-credits](https://developer.herohealth.net/apis/public-api/openapi/practice-group/getsmscreditcount.md): Retrieves the authenticated Practice Group's SMS credit count.

## Patients

Register, search, and manage patient records. Supports PDS (Personal Demographics Service) lookups to trace patients against the NHS Spine.

### Sync Hero patient with EHR

 - [POST /v1/patients/{id}/ehr/connect](https://developer.herohealth.net/apis/public-api/openapi/patients/connectpatientehr.md): Sync a Hero patient with an EHR patient

### Preview Patient Merging

 - [POST /v1/patients/{id}/merge/preview](https://developer.herohealth.net/apis/public-api/openapi/patients/previewpatientmerge.md): Return a preview of a merge between two patients hand provide a merge token

### Merge Patients

 - [POST /v1/patients/{id}/merge](https://developer.herohealth.net/apis/public-api/openapi/patients/mergepatient.md): Merge one patient with another

### Get a Patient

 - [GET /v1/patients/{id}](https://developer.herohealth.net/apis/public-api/openapi/patients/getpatientbyid.md): Retrieve patient information.

### List Patients

 - [GET /v1/patients](https://developer.herohealth.net/apis/public-api/openapi/patients/listpatients.md): Retrieve a list of patients for the practice group. Filter by EMIS ID, NHS number, or date of birth using the field and search query parameters.

### Register a Patient using PDS

 - [POST /v1/patients/register_pds](https://developer.herohealth.net/apis/public-api/openapi/patients/registerpatientpds.md): Register a patient by tracing them against the NHS Spine via PDS (Personal Demographics Service). Provide an NHS number and date of birth, or alternatively a combination of forename, surname, DOB, and postcode.

If the patient already exists in Hero for this practice group, their existing patient_id is returned. If not found, Hero will create a new patient record using the demographics retrieved from PDS.

Common use case: Call this endpoint before sending a message or creating a booking to obtain the Hero patient_id.

### Register a Patient

 - [POST /v1/patients/register](https://developer.herohealth.net/apis/public-api/openapi/patients/registerpatient.md): 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.

### Get Patient Billing Info

 - [GET /v1/patients/{id}/billing_info](https://developer.herohealth.net/apis/public-api/openapi/patients/patientbillinginfo.md): Retrieves billing information for the patient.

### List Patient Payment Methods

 - [GET /v1/patients/{id}/payment_methods](https://developer.herohealth.net/apis/public-api/openapi/patients/listpatientpaymentmethods.md): Retrieves payment methods for default stripe customer of patient.

### Get a Patient

 - [GET /v2/patients/{id}](https://developer.herohealth.net/apis/public-api/openapi/patients/getpatientbyidv2.md): Retrieve patient information.

### List Patients (v2)

 - [GET /v2/patients](https://developer.herohealth.net/apis/public-api/openapi/patients/listpatientsv2.md): Retrieves a list of all patients, from either the EHR or HERO. The verified_email and verified_phone fields search against verified portal credentials (Hero DB only).

### List Patients (v3)

 - [GET /v3/patients](https://developer.herohealth.net/apis/public-api/openapi/patients/listpatientsv3.md): Retrieve a list of patients for the practice group using explicit patient filters.

This endpoint is intended for structured patient search flows where partners can provide named filters such as first_name, last_name, dob, nhs_number, or ehr_partner_id.

Compared with the v2 patients endpoint, v3 supports multi-field search in a single request instead of the older field + search format.

At least one filter must be supplied.

## Episode

Manage clinical episodes — containers for related patient interactions and messages.

### Count Episodes

 - [GET /v1/episodes/count](https://developer.herohealth.net/apis/public-api/openapi/episode/countepisodes.md): Retrieves a count of all episodes for a practice group.

### List Episodes

 - [GET /v1/episodes](https://developer.herohealth.net/apis/public-api/openapi/episode/listepisodes.md): Retrieves a list of all episodes for a practice group.

### Get Episode

 - [GET /v1/episodes/{id}](https://developer.herohealth.net/apis/public-api/openapi/episode/getepisode.md): Retrieve episode information for the given ID.

### Update an episode

 - [PATCH /v1/episodes/{id}](https://developer.herohealth.net/apis/public-api/openapi/episode/updateepisode.md): Updates an episode using the provided parameters.

### Create a note

 - [POST /v1/notes](https://developer.herohealth.net/apis/public-api/openapi/episode/createepisodenote.md): Create a note for an episode in inbox.

### List Episodes (v2)

 - [GET /v2/episodes](https://developer.herohealth.net/apis/public-api/openapi/episode/listepisodesv2.md): Retrieves a list of all episodes for a practice group.

### Get Episode (v2)

 - [GET /v2/episodes/{id}](https://developer.herohealth.net/apis/public-api/openapi/episode/getepisodev2.md): Retrieves the episode payload using the multi-task view for the given ID.

## Care Navigation

Manage care navigation pathways and patient submissions for triage workflows.

### List Pathways

 - [GET /v1/care-nav/pathways](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/listpathways.md): Retrieves a list of pathways for the requesting practice group.

### Create Pathway

 - [POST /v1/care-nav/pathways](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/createpathway.md): Creates a pathway and its initial submission types for the requesting practice group.

### Get Pathway

 - [GET /v1/care-nav/pathways/{id}](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/getpathway.md): Retrieves a pathway.

### Update Pathway

 - [PATCH /v1/care-nav/pathways/{id}](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/updatepathway.md): Updates a pathway for the requesting practice group.

### Delete Pathway

 - [DELETE /v1/care-nav/pathways/{id}](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/deletepathway.md): Soft deletes a pathway for the requesting practice group.

### Get Care Navigation Settings

 - [GET /v1/care-nav/settings](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/getcarenavigationsettings.md): Retrieves the care navigation settings for the requesting practice group.

### Update Care Navigation Settings

 - [PATCH /v1/care-nav/settings](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/updatecarenavigationsettings.md): Updates the care navigation settings for the requesting practice group.

### List Care Navigation Opening Hours

 - [GET /v1/care-nav/opening-hours](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/listcarenavigationopeninghours.md): Lists care navigation opening hours for the requesting practice group.

### Create Care Navigation Opening Hour

 - [POST /v1/care-nav/opening-hours](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/createcarenavigationopeninghour.md): Creates a care navigation opening hour for the requesting practice group.

### Update Care Navigation Opening Hour

 - [PATCH /v1/care-nav/opening-hours/{id}](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/updatecarenavigationopeninghour.md): Updates a single care navigation opening hour for the requesting practice group.

### Delete Care Navigation Opening Hour

 - [DELETE /v1/care-nav/opening-hours/{id}](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/deletecarenavigationopeninghour.md): Deletes a single care navigation opening hour for the requesting practice group.

### Get Care Navigation Submission

 - [GET /v1/care-nav/submissions/{id}](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/getcarenavsubmission.md): Get a care navigation submission and its fields.

### List Care Navigation Submissions

 - [GET /v1/care-nav/submissions](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/listcarenavsubmissions.md): Retrieves a list of all care navigation submissions.

### Create Care Nav Submission

 - [POST /v1/care-nav/submission](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/createsubmission.md): Create a Care Nav Submission.

### List Submission Types

 - [GET /v1/care-nav/submission-types](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/listsubmissiontype.md): Retrieves a list of submission types for the requesting practice group.

### Create Submission Type

 - [POST /v1/care-nav/submission-types](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/createsubmissiontype.md): Creates a submission type for an existing pathway in the requesting practice group.

### Get Submission Type

 - [GET /v1/care-nav/submission-types/{id}](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/getsubmissiontype.md): Retrieves a submission type.

### Update Submission Type

 - [PATCH /v1/care-nav/submission-types/{id}](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/updatesubmissiontype.md): Updates a submission type for the requesting practice group.

### Archive Submission Type

 - [DELETE /v1/care-nav/submission-types/{id}](https://developer.herohealth.net/apis/public-api/openapi/care-navigation/archivesubmissiontype.md): Archives a submission type for the requesting practice group.

## WriteToRecord

Check the status of write-to-record operations for messages sent to the EHR.

### Get Write to Record status

 - [GET /v1/write-to-record/status](https://developer.herohealth.net/apis/public-api/openapi/writetorecord/getwritetorecordstatus.md): Get the latest Write to Record status for a resource.

## Task

Manage tasks assigned to admin users.

### Update a task (deprecated)

 - [PATCH /v1/tasks/{id}](https://developer.herohealth.net/apis/public-api/openapi/task/updatetask.md): Updates a task using the provided parameters.

### Get Task (deprecated)

 - [GET /v2/tasks/{id}](https://developer.herohealth.net/apis/public-api/openapi/task/gettask.md): Retrieve task information for the given ID.

### List Tasks (deprecated)

 - [GET /v2/tasks](https://developer.herohealth.net/apis/public-api/openapi/task/listtasks.md): Retrieves a list of all tasks for a practice group.

## Individual messages

Send SMS, email, NHS App, and Hero-only messages to patients. Supports write-to-record to persist messages in the patient's EHR.

### Get Message

 - [GET /v1/messages/{id}](https://developer.herohealth.net/apis/public-api/openapi/individual-messages/getmessage.md): Retrieves a message by its ID.

### Send a Message

 - [POST /v1/messages/send](https://developer.herohealth.net/apis/public-api/openapi/individual-messages/sendmessage.md): 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.

### Get Message Status

 - [GET /v1/messages/{id}/status](https://developer.herohealth.net/apis/public-api/openapi/individual-messages/getstatus.md): Retrieve message write to record and send status

### List Assignee Collection

 - [GET /v1/messages/assignee/collection](https://developer.herohealth.net/apis/public-api/openapi/individual-messages/assigneecollections.md): Retrieve a list of all assignees including Admin or AdminTeam for the requesting practice group and admin

### Search SNOMED concepts

 - [GET /v1/snomed](https://developer.herohealth.net/apis/public-api/openapi/individual-messages/searchsnomed.md): Searches by code when query is numeric (a single code or a comma-separated list of codes), otherwise searches by free-text term.

### List Templates

 - [GET /v1/templates](https://developer.herohealth.net/apis/public-api/openapi/individual-messages/listtemplates.md): Retrieves a list of message templates for the requesting practice group.

### Get Automated Message

 - [GET /v2/automated_messages/{id}](https://developer.herohealth.net/apis/public-api/openapi/individual-messages/getautomatedmessage.md): Retrieve automated message for the given ID.

### List Sent Messages

 - [GET /v2/sent_messages](https://developer.herohealth.net/apis/public-api/openapi/individual-messages/listsentmessages.md): Retrieves a list of all sent messages.

### Validate a SNOMED Code (deprecated)

 - [POST /v1/snomed/validate](https://developer.herohealth.net/apis/public-api/openapi/individual-messages/validatesnomed.md): Deprecated. Use GET /v1/snomed with the code as the query parameter to validate a SNOMED code instead — a non-empty result confirms the code is valid.

## Batch messages

Create, send, and track batch messages and their recipients.

### Create a Batch Message

 - [POST /v1/batch_message](https://developer.herohealth.net/apis/public-api/openapi/batch-messages/createbatchmessage.md): Create a Batch Message

### List Batch Messages

 - [GET /v1/batch_message](https://developer.herohealth.net/apis/public-api/openapi/batch-messages/listbatchmessages.md): List Batch Messages

### Send a Batch Message

 - [PATCH /v1/batch_message/{id}/send](https://developer.herohealth.net/apis/public-api/openapi/batch-messages/sendbatchmessage.md): Send a Batch Message

### Get a Batch Message

 - [GET /v1/batch_message/{id}](https://developer.herohealth.net/apis/public-api/openapi/batch-messages/getbatchmessage.md): Get a Batch Message

### List Batch Message Recipients

 - [GET /v1/batch_message/{id}/recipients](https://developer.herohealth.net/apis/public-api/openapi/batch-messages/listrecipients.md): List Batch Message Recipients

### List Batch Message Sends

 - [GET /v1/batch_message/{id}/messages](https://developer.herohealth.net/apis/public-api/openapi/batch-messages/listbatchmessagesends.md): List Batch Message Sends

## Links

Generate and manage booking links, form links, and short links for patient self-service flows.

### Create an Attachment Link

 - [POST /v1/attachment_links](https://developer.herohealth.net/apis/public-api/openapi/links/createattachmentlink.md): Creates a attachment link using the provided parameters.

### Create a Booking Link

 - [POST /v1/booking_links](https://developer.herohealth.net/apis/public-api/openapi/links/createbookinglink.md): Create a booking link that can be shared with a patient. The link allows the patient to self-book into an available appointment slot.

Booking links are tied to a specific patient and appointment type. The generated URL can be sent via SMS or email using the Send Message endpoint.

### Update a Booking Link

 - [PATCH /v1/booking_links/{id}](https://developer.herohealth.net/apis/public-api/openapi/links/updatebookinglink.md): Updates a booking link using the provided parameters.

### Create a Form Link

 - [POST /v1/form_links](https://developer.herohealth.net/apis/public-api/openapi/links/createformlink.md): Creates a form link using the provided parameters.

### Get Link Status

 - [GET /v1/links/status](https://developer.herohealth.net/apis/public-api/openapi/links/getlinkstatus.md): Get the status of a given link.

### List Short links

 - [GET /v1/short_links](https://developer.herohealth.net/apis/public-api/openapi/links/listshortlinks.md): Retrieves a list of shortlinks filtered by given parameters.

### Create a Video Link

 - [POST /v1/video_links](https://developer.herohealth.net/apis/public-api/openapi/links/createvideolink.md): Creates a video link using the provided parameters.

## Webhooks

Subscribe to Hero events (e.g. appointment confirmations, write-to-record outcomes) and receive real-time notifications via HTTP callbacks.

### Create a Webhook

 - [POST /v1/webhooks](https://developer.herohealth.net/apis/public-api/openapi/webhooks/createwebhook.md): Create a webhook subscription for the authenticated practice group. Hero will send an HTTP POST request to the specified URL whenever the subscribed event occurs.

Available events: appointment.confirmed, appointment.cancelled, appointment.rescheduled, prescription.issued, patient.added-to-sequence, write-to-record.succeeded, write-to-record.failed.

Optionally provide a signing_key to enable HMAC-SHA256 signature verification on incoming webhook requests. See the webhook security documentation for verification examples.

### List Webhooks

 - [GET /v1/webhooks](https://developer.herohealth.net/apis/public-api/openapi/webhooks/listwebhooks.md): Retrieve all webhook subscriptions for the authenticated practice group. Use this to audit active subscriptions or check event types you are subscribed to.

### Delete a Webhook

 - [DELETE /v1/webhooks/{id}](https://developer.herohealth.net/apis/public-api/openapi/webhooks/deletewebhook.md): Delete a webhook subscription. Hero will immediately stop sending events to the webhook URL. This action cannot be undone — you will need to create a new webhook to resubscribe.

### List Webhook Executions

 - [GET /v1/webhooks/{id}/executions](https://developer.herohealth.net/apis/public-api/openapi/webhooks/listwebhookexecutions.md): Retrieves a list of executions for a specific webhook.

## Invoicing

Manage invoices, coupons, and products for a practice group.

### List Coupons

 - [GET /v1/invoicing/coupons](https://developer.herohealth.net/apis/public-api/openapi/invoicing/listcoupons.md): Retrieves a list of Stripe coupons for the requesting practice group.

### Create Invoice

 - [POST /v1/invoicing/invoices](https://developer.herohealth.net/apis/public-api/openapi/invoicing/createinvoice.md): 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.

### Update Invoice

 - [PATCH /v1/invoicing/invoices/{id}](https://developer.herohealth.net/apis/public-api/openapi/invoicing/updateinvoice.md): 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.

### Link Invoice to Appointment

 - [POST /v1/invoicing/invoices/link](https://developer.herohealth.net/apis/public-api/openapi/invoicing/linkinvoice.md): Links an external Stripe invoice to an appointment.

This endpoint finds or creates a Hero invoice record from a Stripe invoice ID,
then links it to the specified appointment.

### List Products

 - [GET /v1/invoicing/products](https://developer.herohealth.net/apis/public-api/openapi/invoicing/listproducts.md): Retrieves a list of Stripe products for the requesting practice group.

## Memberships

Manage notification subscriptions, subscribers, membership policies, and membership schemes.

### Create Membership Policy

 - [POST /v1/invoicing/membership-policies](https://developer.herohealth.net/apis/public-api/openapi/memberships/createmembershippolicy.md): Creates a new membership policy for the requesting practice group.

### List Membership Schemes

 - [GET /v1/invoicing/membership-schemes](https://developer.herohealth.net/apis/public-api/openapi/memberships/listmembershipschemes.md): Retrieves a list of membership schemes for the requesting practice group.

### List Subscriptions

 - [GET /v1/subscriptions](https://developer.herohealth.net/apis/public-api/openapi/memberships/listsubscriptions.md): Retrieves a list of subscriptions for a practice group.

### List Subscribers

 - [GET /v1/subscribers](https://developer.herohealth.net/apis/public-api/openapi/memberships/listsubscribers.md): Retrieves a list of subscribers for a practice group.

## Prescriptions

Create, list, and manage prescriptions.

### Get Prescriber's Pharmacies List

 - [GET /v1/prescriber/{id}/pharmacies](https://developer.herohealth.net/apis/public-api/openapi/prescriptions/listprescriberpharmacies.md): Retrieve a list of pharmacies for the prescriber.

### Create Pharmacy

 - [POST /v1/pharmacies](https://developer.herohealth.net/apis/public-api/openapi/prescriptions/createpharmacy.md): Create a new Pharmacy for the prescriber.

### Create a Prescription

 - [POST /v1/prescriptions](https://developer.herohealth.net/apis/public-api/openapi/prescriptions/createprescription.md): Create a new prescription for a patient.

### Get a Prescription

 - [GET /v1/prescriptions/{id}](https://developer.herohealth.net/apis/public-api/openapi/prescriptions/getprescriptionbyid.md): Retrieve details of a specific prescription by its ID.

### List Prescriptions

 - [GET /v2/prescriptions](https://developer.herohealth.net/apis/public-api/openapi/prescriptions/listprescriptions.md): Retrieves a list of all prescriptions for a patient.

### Create Prescription with Patient

 - [POST /v2/prescriptions](https://developer.herohealth.net/apis/public-api/openapi/prescriptions/createprescriptionwithpatient.md): Creates a new prescription and associates it with a patient.

### Get Prescriber (deprecated)

 - [GET /v1/prescriber/{id}](https://developer.herohealth.net/apis/public-api/openapi/prescriptions/getprescriber.md): Retrieves a prescriber by its ID.

## Customers

Create, list, and retrieve invoicing customers for a practice group.

### List Customers

 - [GET /v1/invoicing/customers](https://developer.herohealth.net/apis/public-api/openapi/customers/listcustomers.md): Retrieves a list of Stripe customers for the requesting practice group.

### Create Customer

 - [POST /v1/invoicing/customers](https://developer.herohealth.net/apis/public-api/openapi/customers/createcustomer.md): Creates a new Stripe customer for the requesting practice group.

### Get Default Customer

 - [GET /v1/invoicing/customers/default](https://developer.herohealth.net/apis/public-api/openapi/customers/getdefaultcustomer.md): Retrieves the default Stripe customer for a patient.

## Form

List and retrieve forms (questionnaires) configured for a practice group.

### List Forms

 - [GET /v1/forms](https://developer.herohealth.net/apis/public-api/openapi/form/listforms.md): Retrieves a list of all forms configured for the requesting practice group.

### Create Form

 - [POST /v1/forms](https://developer.herohealth.net/apis/public-api/openapi/form/createform.md): Create a new form template with fields.

### Update Form

 - [PUT /v1/forms/{id}](https://developer.herohealth.net/apis/public-api/openapi/form/updateform.md): Update an existing form template, replacing all fields.

### Get Form

 - [GET /v1/forms/{id}](https://developer.herohealth.net/apis/public-api/openapi/form/getform.md): Get a form and its fields.

### Create Form Response

 - [POST /v1/forms/{id}/response](https://developer.herohealth.net/apis/public-api/openapi/form/createresponse.md): Create a response for a given Form ID.

### Update Form Response

 - [POST /v1/forms/response/{id}](https://developer.herohealth.net/apis/public-api/openapi/form/updateformresponse.md): Update form response for a given form response ID.

## Form Response

Create, retrieve, and update form responses submitted by patients.

### Get FormResponse

 - [GET /v1/form_response/{id}](https://developer.herohealth.net/apis/public-api/openapi/form-response/getformresponse.md): Get a form response and its fields.

### Get FormSubmissionResponse

 - [GET /v1/form_submission_response/{id}](https://developer.herohealth.net/apis/public-api/openapi/form-response/getformsubmissionresponsedata.md): Get a form submission response and its fields.

### List Form Responses

 - [GET /v2/form_responses](https://developer.herohealth.net/apis/public-api/openapi/form-response/listformresponses.md): Retrieves a list of all form responses.