# 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


```json
{
  "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.


```json
{
  "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



```json
{
  "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:


```json
{
  "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


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

### NHS identifiers


```json
{
  "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:


```json
{
  "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](mailto:support@herohealth.net).

## Next steps

- [Your first API call](/pages/api/get-started/your-first-api-call) — make a working API request end-to-end
- [API Reference](/apis/public-api/openapi) — full endpoint documentation