{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-pages/api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Using Elements vs APIs","description":"Healthcare APIs and embeddable Elements for patient messaging, appointment booking and clinical record access. Integrated with EMIS Web and TPP SystmOne.","siteUrl":"https://developer.herohealth.net","lang":"en-GB","meta":[{"name":"og:type","content":"website"},{"name":"og:image","content":"https://developer.herohealth.net/images/logo.png"},{"name":"og:site_name","content":"Hero Health Developer Portal"},{"name":"twitter:card","content":"summary"},{"name":"twitter:image","content":"https://developer.herohealth.net/images/logo.png"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"using-elements-vs-apis","__idx":0},"children":["Using Elements vs APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose the right integration approach for your healthcare application based on your development needs, timeline, and customisation requirements."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-decision-guide","__idx":1},"children":["Quick decision guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Choose Elements if you want to:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Get up and running quickly with minimal development effort"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use Hero's proven, NHS-compliant UX patterns out of the box"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Minimise development and ongoing maintenance overhead"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Focus engineering resource on your core product features"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Choose APIs if you want to:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create fully custom user experiences with complete control over UI/UX"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Integrate deeply with existing clinical workflows or data models"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Build unique functionality on top of Hero's healthcare infrastructure"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"comparison","__idx":2},"children":["Comparison"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Factor"},"children":["Factor"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Elements"},"children":["Elements"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"APIs"},"children":["APIs"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Time to market"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hours"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Days to weeks"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Development effort"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Low"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Moderate to high"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["UI/UX control"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hero's design (themeable)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Complete control"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Maintenance"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hero maintains"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You maintain"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Customisation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Limited to theming"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unlimited"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update management"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Automatic"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Manual implementation"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-started","__idx":3},"children":["Getting started"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"starting-with-elements","__idx":4},"children":["Starting with Elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Elements are distributed as private npm packages. To get started you'll need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["GitHub Personal Access Token (PAT)"]}," — issued by Hero, required to install private packages from our npm registry"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API key"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["practice group ID"]}," — to authenticate your Elements at runtime via short-lived access tokens"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"mailto:support@herohealth.net"},"children":["Hero support"]}," to request credentials, and see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/pages/elements/setup"},"children":["Elements setup guide"]}," for full installation instructions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"starting-with-apis","__idx":5},"children":["Starting with APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All you need is an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API key"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["practice group ID"]},". Read the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/pages/api/authentication"},"children":["Authentication guide"]}," then follow ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/pages/api/get-started/your-first-api-call"},"children":["Your first API call"]}," to make a working request in minutes."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-use-cases","__idx":6},"children":["Common use cases"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"when-elements-are-the-right-choice","__idx":7},"children":["When Elements are the right choice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"when-apis-are-the-right-choice","__idx":8},"children":["When APIs are the right choice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hybrid-approach","__idx":9},"children":["Hybrid approach"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You don't have to choose one or the other. Many integrations use both:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Elements"]}," for standard flows (messaging, booking, consultation) that don't need custom UI"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["APIs"]}," for unique features, custom reporting, or deep integration with existing systems"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"migration-path","__idx":10},"children":["Migration path"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"from-elements-to-apis","__idx":11},"children":["From Elements to APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"from-apis-to-elements","__idx":12},"children":["From APIs to Elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":13},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Ready to embed?"]}," Start with the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/pages/elements/introduction"},"children":["Elements documentation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Building with APIs?"]}," Read the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/pages/api/authentication"},"children":["Authentication guide"]}," and ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/pages/api/get-started/your-first-api-call"},"children":["Your first API call"]}]}]}]},"headings":[{"value":"Using Elements vs APIs","id":"using-elements-vs-apis","depth":1},{"value":"Quick decision guide","id":"quick-decision-guide","depth":2},{"value":"Comparison","id":"comparison","depth":2},{"value":"Getting started","id":"getting-started","depth":2},{"value":"Starting with Elements","id":"starting-with-elements","depth":3},{"value":"Starting with APIs","id":"starting-with-apis","depth":3},{"value":"Common use cases","id":"common-use-cases","depth":2},{"value":"When Elements are the right choice","id":"when-elements-are-the-right-choice","depth":3},{"value":"When APIs are the right choice","id":"when-apis-are-the-right-choice","depth":3},{"value":"Hybrid approach","id":"hybrid-approach","depth":2},{"value":"Migration path","id":"migration-path","depth":2},{"value":"From Elements to APIs","id":"from-elements-to-apis","depth":3},{"value":"From APIs to Elements","id":"from-apis-to-elements","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Using Elements vs APIs","description":"Choose between Hero Health Elements and APIs based on your timeline, customisation requirements, and development resource.","seo":{"title":"Using Elements vs APIs"}},"lastModified":"2026-04-08T14:06:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pages/api/guides/using-elements-vs-apis","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}