API Reference

List Batch Messages

Hero Health Public API (1.0.0)

Download OpenAPI description

Download API docs

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

Operations

Admin

Operations

ApiKey

Operations

Booking

Operations

Links

Operations

Utilities

Operations

Messages

Operations

Create a Batch Message

Request

Create a Batch Message

Bodyapplication/jsonrequired

namestringrequired

channelstringrequired

Enum"SMS""EMAIL""NHS_APP"

subjectstring

The subject is required when channel = EMAIL

contentstringrequired

recipientsArray of objects or objectsrequired

One of:

recipients[].nhs_numberstringrequired

recipients[].dobstring or null(date-time)required

curl -i -X POST \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/batch_message \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE' \
  -d '{
    "name": "string",
    "channel": "SMS",
    "subject": "string",
    "content": "string",
    "recipients": [
      {
        "nhs_number": "string",
        "dob": "2019-08-24T14:15:22Z"
      }
    ]
  }'

Responses

Bodyapplication/json

idstringrequired

namestringrequired

statusstringrequired

Enum"CREATED""PENDING""SENDING""COMPLETED"

channelstringrequired

Enum"SMS""EMAIL""NHS_APP"

subjectstring

contentstringrequired

Response

application/json

{
  "id": "string",
  "name": "string",
  "status": "CREATED",
  "channel": "SMS",
  "subject": "string",
  "content": "string"
}

List Batch Messages

Request

List Batch Messages

Query

page_sizeinteger

page_indexinteger

statusstring

Enum"CREATED""ENRICHMENT_ERROR""ENRICHED""INVALID_PAYLOAD""QUEUED"

curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/batch_message?page_index=0&page_size=0&status=CREATED' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

idstringrequired

namestringrequired

statusstringrequired

Enum"CREATED""PENDING""SENDING""COMPLETED"

channelstringrequired

Enum"SMS""EMAIL""NHS_APP"

subjectstring

contentstringrequired

Response

application/json

{
  "id": "string",
  "name": "string",
  "status": "CREATED",
  "channel": "SMS",
  "subject": "string",
  "content": "string"
}

Send a Batch Message

Request

Send a Batch Message

Path

idstringrequired

curl -i -X PATCH \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/batch_message/{id}/send' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Response

No content

Get a Batch Message

Request

Get a Batch Message

Path

idstringrequired

curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/batch_message/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

idstringrequired

namestringrequired

statusstringrequired

Enum"CREATED""PENDING""SENDING""COMPLETED"

channelstringrequired

Enum"SMS""EMAIL""NHS_APP"

subjectstring

contentstringrequired

Response

application/json

{
  "id": "string",
  "name": "string",
  "status": "CREATED",
  "channel": "SMS",
  "subject": "string",
  "content": "string"
}

List Batch Message Recipients

Request

List Batch Message Recipients

Path

idstringrequired

Query

page_sizeinteger

page_indexinteger

statusstring

Enum"CREATED""ENRICHMENT_ERROR""ENRICHED""INVALID_PAYLOAD""QUEUED"

curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/batch_message/{id}/recipients?page_index=0&page_size=0&status=CREATED' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

dataArray of objectsrequired

data[].enrichment_statusstringrequired

Enum"CREATED""ENRICHMENT_ERROR""ENRICHED""INVALID_PAYLOAD""QUEUED"

data[].first_namestring

data[].last_namestring

data[].nhs_numberstring

data[].mobilestring

data[].emailstring

countnumberrequired

Response

application/json

{
  "data": [
    { … }
  ],
  "count": 0
}

List Batch Message Sends

Request

List Batch Message Sends

Path

idstringrequired

Query

page_sizeinteger

page_indexinteger

statusstring

Enum"CREATED""QUEUED""SENT""ERROR""SUCCESS"

curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/batch_message/{id}/messages?page_index=0&page_size=0&status=CREATED' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

dataArray of objectsrequired

data[].idstringrequired

data[].statusstringrequired

data[].subjectstring or null

data[].recipientstringrequired

data[].channelstringrequired

Enum"SMS""EMAIL""NHS_APP"

data[].contentstringrequired

data[].sent_atstring or null(date-time)required

data[].created_atstring or null(date-time)required

countnumberrequired

Response

application/json

{
  "data": [
    { … }
  ],
  "count": 0
}

Get Message

Request

Retrieves a message by its ID.

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

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

Sends a message for a given patient to Hero. It has optional parameters relating to the message being sent.

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

Flags if the message should be encrypted

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": "string",
    "message_type": "hero",
    "message_string": "string",
    "recipient_contact_detail": "string",
    "fallback_contact_detail": "string",
    "fallback_message_type": "sms",
    "write_to_record": false,
    "encrypted": false,
    "snomed_code": "string",
    "snomed_term": "string",
    "auto_write_to_record": false,
    "task_id": "string",
    "attachment_uuid": "string",
    "short_link_id": "string",
    "assignee_id": 0,
    "assignee_type": "string",
    "send_at": "2019-08-24T14:15:22Z"
  }'

Responses

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

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

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"
  }
}

List Assignee Collection

Request

Retrieve a list of all assignees including Admin or AdminTeam for the requesting practice group and admin

curl -i -X GET \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/messages/assignee/collection \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

dataArray of objectsrequired

data[].labelstringrequired

data[].valuenumber or nullrequired

data[].typestringrequired

data[].keystringrequired

Response

application/json

{
  "data": [
    { … }
  ]
}

Validate a SNOMED Code

Request

Bodyapplication/jsonrequired

codestringrequired

curl -i -X POST \
  https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/snomed/validate \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE' \
  -d '{
    "code": "string"
  }'

Responses

Bodyapplication/json

validbooleanrequired

Response

application/json

{
  "valid": true
}

List Templates

Request

Retrieves a list of message templates for the requesting practice group.

Query

has_follow_upboolean

curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v1/templates?has_follow_up=true' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

dataArray of objectsrequired

data[].idstringrequired

data[].namestringrequired

data[].contentstringrequired

data[].linkstring

Default "no_link"

Enum"no_link""booking""form"

data[].typestring

Default "hero"

Enum"hero""external""user"

data[].sms_snomed_codestring or null

data[].sms_follow_up_1_snomed_codestring or null

data[].sms_follow_up_2_snomed_codestring or null

data[].email_snomed_codestring or null

data[].email_follow_up_1_snomed_codestring or null

data[].email_follow_up_2_snomed_codestring or null

data[].send_follow_up_oneboolean

Default false

data[].send_follow_up_twoboolean

Default false

data[].reminder_timenumber or null

countnumberrequired

Response

application/json

{
  "data": [
    { … }
  ],
  "count": 0
}

Get Automated Message

Request

Retrieve automated message for the given ID.

Path

idstringrequired

curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v2/automated_messages/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

idstringrequired

recipientobject or null

subjectstring or null

channelstring or null

contentstring or null

contact_detailstring or null

sent_atstring or null(date-time)

statusstring or null

message_typestring or null

appointmentobject or null

notification_typestring or null

Response

application/json

{
  "id": "string",
  "recipient": {
    "id": "string",
    "title": "Baron",
    "first_name": "string",
    "last_name": "string"
  },
  "subject": "string",
  "channel": "string",
  "content": "string",
  "contact_detail": "string",
  "sent_at": "2019-08-24T14:15:22Z",
  "status": "string",
  "message_type": "string",
  "appointment": {
    "id": "string",
    "type": "string",
    "start_time": "2019-08-24T14:15:22Z"
  },
  "notification_type": "string"
}

List Sent Messages

Request

Retrieves a list of all sent messages.

Query

page_indexstring

page_sizestring

order_bystring

Enum"patient_first_name""patient_last_name""patient_full_name""created_at""sent_at"

order_descendingboolean

patient_first_namestring

patient_last_namestring

patient_full_namestring

patient_idstring

recipient_contact_detailstring

write_to_record_statusstring

Enum"success""failed""not_written"

message_typestring or Array of strings

One of:

string

Enum"nhs_app""email""hero""sms"

short_link_idstring

short_link_typestring

campaign_idstring

statusstring or Array of strings

One of:

string

Enum"delivered""declined""sent""pending""retry""fatal"

scheduledboolean

sent_bystring

sent_at[]Array of strings

scheduled_at[]Array of strings

curl -i -X GET \
  'https://developer.herohealth.net/_mock/apis/public-api/openapi/v2/sent_messages?campaign_id=string&message_type=nhs_app&order_by=patient_first_name&order_descending=true&page_index=string&page_size=string&patient_first_name=string&patient_full_name=string&patient_id=string&patient_last_name=string&recipient_contact_detail=string&scheduled=true&scheduled_at%5B%5D=string&sent_at%5B%5D=string&sent_by=string&short_link_id=string&short_link_type=string&status=delivered&write_to_record_status=success' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-practice-group-id: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

dataArray of objectsrequired

data[].idstring^\d+$required

data[].patientobjectrequired

data[].patient.idstring^\d+$required

data[].patient.titlestring or nullrequired

Enum"Baron""Baroness""Brigadier""Count""Colonel""Countess""Captain""Dame""The Dowager Viscountess""Dr"

data[].patient.first_namestringrequired

data[].patient.last_namestringrequired

data[].write_to_recordobjectrequired

data[].write_to_record.write_to_record_atstring or null(date-time)required

data[].write_to_record.statusstring or nullrequired

data[].write_to_record.failure_reasonstring or nullrequired

data[].write_to_record.snomed_codestring or nullrequired

data[].short_linkobject or nullrequired

data[].short_link.idstring or null^\d+$

data[].short_link.typestring or null

data[].short_link.namestring or null

data[].short_link.statusstring or null

data[].campaignobject or nullrequired

data[].campaign.idstring or null^\d+$

data[].campaign.namestring or null

data[].created_atstring or null(date-time)required

data[].sent_atstring or null(date-time)required

data[].scheduled_atstring or null(date-time)required

data[].statusstringrequired

Enum"delivered""declined""sent""pending""retry""fatal"

data[].sent_bystringrequired

data[].recipient_contact_detailstringrequired

data[].message_typestringrequired

data[].messagestring or nullrequired

countnumberrequired

Response

application/json

{
  "data": [
    { … }
  ],
  "count": 0
}

Booking - HCA

Operations

Consultations

Operations

Episode

Operations

Form

Operations

Form Response

Operations

Invoicing

Operations

Partner

Operations

Partners

Operations

Patients

Operations

Prescription

Operations

Subscriptions

Operations

Task

Operations

Webhooks

Operations

Prescriptions

Operations

Hero Health Public API (1.0.0)

Practice Group

Admin

ApiKey

Booking

Links

Utilities

Messages

Create a Batch Message

RequestExpand all

Responses

Was this helpful?

List Batch Messages

Request

Responses

Was this helpful?

Send a Batch Message

Request

Responses

Was this helpful?

Get a Batch Message

Request

Responses

Was this helpful?

List Batch Message Recipients

Request

Responses

Was this helpful?

List Batch Message Sends

Request

Responses

Was this helpful?

Get Message

Request

Responses

Was this helpful?

Send a Message

RequestExpand all

Responses

Was this helpful?

Get Message Status

Request

Responses

Was this helpful?

List Assignee Collection

Request

Responses

Was this helpful?

Validate a SNOMED Code

Request

Responses

Was this helpful?

List Templates

Request

Responses

Was this helpful?

Get Automated Message

Request

Responses

Was this helpful?

List Sent Messages

RequestExpand all

Responses

Was this helpful?

Booking - HCA

Care Navigation

Consultations

Episode

Form

Form Response

Invoicing

Partner

Partners

Patients

Prescription

Subscriptions

Task

Webhooks

Prescriptions

Request

Request

Request