API docs by Redocly

HearLink API (1.0.0)

Download OpenAPI specification:

License: MIT

Programmatic access to HearLink services.

Patients

Manage patient records.

Create a patient

Creates a new patient.
Field groups (exactly one required per group): - referralId or referralName - primaryClinicId or primaryClinicName - statusId or statusName

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
title
string
fullName
required
string non-empty
object (Address)

Patient address details

referralId
string

Provide exactly one of referralId or referralName

referralName
string

Provide exactly one of referralId or referralName

primaryClinicId
string

Provide exactly one of primaryClinicId or primaryClinicName

primaryClinicName
string

Provide exactly one of primaryClinicId or primaryClinicName

statusId
string

Provide exactly one of statusId or statusName

statusName
string

Provide exactly one of statusId or statusName

primaryPhoneNumber
required
string non-empty
secondaryPhoneNumber
string
emailAddress
string <email>
dob
string^\d{4}-\d{2}-\d{2}$

Optional date of birth in YYYY-MM-DD format

age
integer >= 0
gender
string
notes
string
required
object (Tracking)

Tracking/marketing information

Responses

Request samples

Content type
application/json
{
  • "fullName": "John Smith",
  • "primaryPhoneNumber": "07123456789",
  • "emailAddress": "[email protected]",
  • "dob": "1985-07-12",
  • "statusName": "Patient Created",
  • "primaryClinicName": "Manchester",
  • "referralName": "Facebook",
  • "tracking": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Webhooks

Webhooks send real-time HTTP POST notifications to a URL you configure whenever events occur in HearLink.

Envelope

Every delivery wraps entity data in a standard envelope:

{
  "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  "type": "patient.created",
  "createdAt": "2026-04-10T14:30:00.000Z",
  "data": { ... }
}

Headers

Header Description
X-HearLink-Signature t=<unix>,v1=<hmac-sha256> — verify authenticity
X-HearLink-Event The event type, e.g. patient.created
X-HearLink-Delivery Unique ID for this delivery attempt

Signature verification

Compute HMAC-SHA256(secret, "{timestamp}.{raw_body}") and compare to the v1 value.

Node.js example:

const crypto = require('crypto');

function verifySignature(rawBody, secret, signatureHeader) {
  const [tPart, v1Part] = signatureHeader.split(',');
  const timestamp = tPart.replace('t=', '');
  const expected = v1Part.replace('v1=', '');
  const computed = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(expected),
  );
}

Retries

Failed deliveries (non-2xx or timeout after 30s) are retried up to 5 times with exponential back-off. After 50 consecutive failures across any events, the webhook is automatically disabled.

Data notes

  • All Firestore timestamps are serialised to ISO 8601 strings.
  • Related entities include a slim patient reference (uid, fullName, optional tracking) rather than the full patient document.
  • Sensitive fields (signatures, medical numbers, verification tokens) are stripped before delivery.

Patient Created Webhook

Fired when a new patient record is created.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Patient Updated Webhook

Fired when a patient record is modified.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Patient Deleted Webhook

Fired when a patient record is deleted.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Appointment Created Webhook

Fired when a new appointment is created.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Appointment Updated Webhook

Fired when an appointment is modified (including status changes like confirmed, cancelled, arrived, no-show).

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Appointment Deleted Webhook

Fired when an appointment is deleted.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Invoice Created Webhook

Fired when a new invoice is created.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Invoice Updated Webhook

Fired when an invoice is modified.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Invoice Deleted Webhook

Fired when an invoice is deleted.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Transaction Created Webhook

Fired when a new transaction (payment or refund) is created.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Transaction Updated Webhook

Fired when a transaction is modified.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Transaction Deleted Webhook

Fired when a transaction is deleted.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Credit Note Created Webhook

Fired when a new credit note is created.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Credit Note Updated Webhook

Fired when a credit note is modified.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Credit Note Deleted Webhook

Fired when a credit note is deleted.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Hearing Test Created Webhook

Fired when a new hearing test is recorded.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Hearing Test Updated Webhook

Fired when a hearing test is modified.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Hearing Test Deleted Webhook

Fired when a hearing test is deleted.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Test Event Webhook

Sent when a user clicks the "Test" button in the portal. Not subscribable — always delivered to the webhook being tested.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
id
required
string

Unique event ID prefixed with evt_.

type
required
string

The event type.

createdAt
required
string <date-time>

ISO 8601 timestamp of when the event was created.

required
object

The entity payload. Shape varies by event type.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "type": "patient.created",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}