# Using Elements vs APIs

Choose the right integration approach for your healthcare application based on your development needs, timeline, and customisation requirements.

## Quick decision guide

**Choose Elements if you want to:**

- Get up and running quickly with minimal development effort
- Use Hero's proven, NHS-compliant UX patterns out of the box
- Minimise development and ongoing maintenance overhead
- Focus engineering resource on your core product features


**Choose APIs if you want to:**

- Create fully custom user experiences with complete control over UI/UX
- Integrate deeply with existing clinical workflows or data models
- Build unique functionality on top of Hero's healthcare infrastructure


## Comparison

| Factor | Elements | APIs |
|  --- | --- | --- |
| **Time to market** | Hours | Days to weeks |
| **Development effort** | Low | Moderate to high |
| **UI/UX control** | Hero's design (themeable) | Complete control |
| **Maintenance** | Hero maintains | You maintain |
| **Customisation** | Limited to theming | Unlimited |
| **Update management** | Automatic | Manual implementation |


## Getting started

### Starting with Elements

Elements are distributed as private npm packages. To get started you'll need:

- A **GitHub Personal Access Token (PAT)** — issued by Hero, required to install private packages from our npm registry
- An **API key** and **practice group ID** — to authenticate your Elements at runtime via short-lived access tokens


Contact [Hero support](mailto:support@herohealth.net) to request credentials, and see the [Elements setup guide](/pages/elements/setup) for full installation instructions.

### Starting with APIs

All you need is an **API key** and **practice group ID**. Read the [Authentication guide](/pages/api/authentication) then follow [Your first API call](/pages/api/get-started/your-first-api-call) to make a working request in minutes.

## Common use cases

### When Elements are the right choice

**You need to add a standardised patient communication feature quickly.** Embed the Messaging Element to instantly provide messaging capabilities without building and maintaining complex UI components. Hero handles the UX, NHS compliance, and ongoing improvements automatically.

**You're building a patient portal or practice management system** and need appointment booking or consultation flows that just work. Elements let you ship a complete, tested experience without the effort of building from scratch.

### When APIs are the right choice

**You're building a specialised clinical workflow** that needs to integrate messaging or booking data with patient records in a way that reflects your own UI conventions. APIs give you full control to create interfaces that match your clinical workflow and integrate with your existing systems.

**You're serving multiple practices with different branding requirements.** APIs let you build completely customised experiences for each tenant whilst leveraging Hero's backend infrastructure.

## Hybrid approach

You don't have to choose one or the other. Many integrations use both:

- **Elements** for standard flows (messaging, booking, consultation) that don't need custom UI
- **APIs** for unique features, custom reporting, or deep integration with existing systems


**Example**: Use the Appointment Scheduler Element for patient-facing booking, but use the Booking Links API to generate appointment invitations inside your own scheduling workflow.

## Migration path

### From Elements to APIs

If you start with Elements and later need more customisation, Elements continue working whilst you develop API-based features in parallel. Replace Elements with custom implementations gradually — no disruption to existing users.

### From APIs to Elements

If you want to reduce maintenance overhead, identify areas where Hero's pre-built UX covers your needs, implement Elements alongside your existing integration, then deprecate custom UI components over time.

## Next steps

- **Ready to embed?** Start with the [Elements documentation](/pages/elements/introduction)
- **Building with APIs?** Read the [Authentication guide](/pages/api/authentication) and [Your first API call](/pages/api/get-started/your-first-api-call)