Skip to content
API Docs/
/
Basic concepts
Last updated

Basic concepts

Understanding Hero Health's core entities and data model will help you build more effective integrations. This guide covers the key concepts you'll encounter when working with our APIs.

Core entities

Practice groups

The fundamental organisational unit in Hero Health.

What it represents: A GP practice or medical facility within the NHS Key identifier: id — used in the x-practice-group-id header and most API call paths Contains: Practice details, EHR connections, configuration, and booking settings

{
  "id": "practice-abc123",
  "name": "Riverside Medical Centre",
  "sector": "nhs",
  "address": {
    "line_1": "123 High Street",
    "postcode": "SW1A 1AA"
  }
}

Almost every API call requires a practice context. The practice ID scopes your requests to a specific practice and determines what data is accessible.

Authenticated users

Represents the person or system making API calls on behalf of a practice.

{
  "authenticated_as": {
    "id": "user-xyz789",
    "first_name": "Dr. Sarah",
    "last_name": "Johnson",
    "email": "s.johnson@riverside.nhs.uk"
  }
}

The authenticated user determines what data you can access and what actions you can perform.

Patients

The individuals receiving healthcare services.

Accessed through: Messaging, appointment, and communication endpoints

Patient data privacy

Hero Health maintains strict patient data protection. Patient information is only accessible through specific, scoped endpoints designed for healthcare communication.

Appointments and slots

The core components of the scheduling system.

  • Slots: Available time periods that can be booked
  • Appointments: Booked time slots between patients and healthcare providers
{
  "id": "appt-456",
  "start_time": "2024-03-15T14:00:00Z",
  "duration_minutes": 15,
  "status": "confirmed"
}

Relevant when building appointment booking, calendar integrations, or scheduling workflows.

Common data patterns

Timestamps

All timestamps use ISO 8601 format in UTC:

{
  "appointment_time": "2024-03-15T14:00:00Z",
  "created_at": "2024-03-10T09:30:00Z"
}

Convert to Europe/London for display to UK users.

UK addresses

{
  "address": {
    "line_1": "123 High Street",
    "line_2": "Suite 4B",
    "town": "London",
    "county": "Greater London",
    "postcode": "SW1A 1AA",
    "country": "United Kingdom"
  }
}

NHS identifiers

{
  "nhs_number": "9876543210",
  "ods_code": "ABC123"
}

NHS compliance

Hero Health is built for NHS Primary Care:

  • Patient data: Encrypted in transit and at rest
  • Access controls: Role-based permissions scoped per practice
  • Audit trails: All actions logged for NHS England compliance
  • Patient consent: Communications respect patient consent and GDPR preferences

API responses may include compliance-specific errors:

{
  "error": "gdpr_restriction",
  "message": "Patient has restricted data sharing",
  "restrictions": ["sms", "email"]
}

Always respect patient privacy preferences and NHS data protection requirements.

Rate limits

The Hero API enforces a limit of 300 requests per minute per API key. Requests exceeding this limit receive a 429 Too Many Requests response. If your integration requires a higher limit, contact Hero support.

Next steps

Previous page
Next page