{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-pages/api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Basic concepts","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":"basic-concepts","__idx":0},"children":["Basic concepts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"core-entities","__idx":1},"children":["Core entities"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"practice-groups","__idx":2},"children":["Practice groups"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The fundamental organisational unit in Hero Health."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What it represents"]},": A GP practice or medical facility within the NHS"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key identifier"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — used in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-practice-group-id"]}," header and most API call paths"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contains"]},": Practice details, EHR connections, configuration, and booking settings"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"practice-abc123\",\n  \"name\": \"Riverside Medical Centre\",\n  \"sector\": \"nhs\",\n  \"address\": {\n    \"line_1\": \"123 High Street\",\n    \"postcode\": \"SW1A 1AA\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Almost every API call requires a practice context. The practice ID scopes your requests to a specific practice and determines what data is accessible."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authenticated-users","__idx":3},"children":["Authenticated users"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Represents the person or system making API calls on behalf of a practice."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"authenticated_as\": {\n    \"id\": \"user-xyz789\",\n    \"first_name\": \"Dr. Sarah\",\n    \"last_name\": \"Johnson\",\n    \"email\": \"s.johnson@riverside.nhs.uk\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The authenticated user determines what data you can access and what actions you can perform."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"patients","__idx":4},"children":["Patients"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The individuals receiving healthcare services."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Accessed through"]},": Messaging, appointment, and communication endpoints"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Patient data privacy"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hero Health maintains strict patient data protection. Patient information is only accessible through specific, scoped endpoints designed for healthcare communication."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"appointments-and-slots","__idx":5},"children":["Appointments and slots"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The core components of the scheduling system."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Slots"]},": Available time periods that can be booked"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Appointments"]},": Booked time slots between patients and healthcare providers"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"appt-456\",\n  \"start_time\": \"2024-03-15T14:00:00Z\",\n  \"duration_minutes\": 15,\n  \"status\": \"confirmed\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Relevant when building appointment booking, calendar integrations, or scheduling workflows."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-data-patterns","__idx":6},"children":["Common data patterns"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"timestamps","__idx":7},"children":["Timestamps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All timestamps use ISO 8601 format in UTC:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"appointment_time\": \"2024-03-15T14:00:00Z\",\n  \"created_at\": \"2024-03-10T09:30:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Convert to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Europe/London"]}," for display to UK users."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"uk-addresses","__idx":8},"children":["UK addresses"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"address\": {\n    \"line_1\": \"123 High Street\",\n    \"line_2\": \"Suite 4B\",\n    \"town\": \"London\",\n    \"county\": \"Greater London\",\n    \"postcode\": \"SW1A 1AA\",\n    \"country\": \"United Kingdom\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"nhs-identifiers","__idx":9},"children":["NHS identifiers"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"nhs_number\": \"9876543210\",\n  \"ods_code\": \"ABC123\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"nhs-compliance","__idx":10},"children":["NHS compliance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hero Health is built for NHS Primary Care:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Patient data"]},": Encrypted in transit and at rest"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Access controls"]},": Role-based permissions scoped per practice"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Audit trails"]},": All actions logged for NHS England compliance"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Patient consent"]},": Communications respect patient consent and GDPR preferences"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API responses may include compliance-specific errors:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": \"gdpr_restriction\",\n  \"message\": \"Patient has restricted data sharing\",\n  \"restrictions\": [\"sms\", \"email\"]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always respect patient privacy preferences and NHS data protection requirements."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limits","__idx":11},"children":["Rate limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Hero API enforces a limit of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["300 requests per minute"]}," per API key. Requests exceeding this limit receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429 Too Many Requests"]}," response. If your integration requires a higher limit, contact ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"mailto:support@herohealth.net"},"children":["Hero support"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":12},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/pages/api/get-started/your-first-api-call"},"children":["Your first API call"]}," — make a working API request end-to-end"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/public-api/openapi"},"children":["API Reference"]}," — full endpoint documentation"]}]}]},"headings":[{"value":"Basic concepts","id":"basic-concepts","depth":1},{"value":"Core entities","id":"core-entities","depth":2},{"value":"Practice groups","id":"practice-groups","depth":3},{"value":"Authenticated users","id":"authenticated-users","depth":3},{"value":"Patients","id":"patients","depth":3},{"value":"Appointments and slots","id":"appointments-and-slots","depth":3},{"value":"Common data patterns","id":"common-data-patterns","depth":2},{"value":"Timestamps","id":"timestamps","depth":3},{"value":"UK addresses","id":"uk-addresses","depth":3},{"value":"NHS identifiers","id":"nhs-identifiers","depth":3},{"value":"NHS compliance","id":"nhs-compliance","depth":2},{"value":"Rate limits","id":"rate-limits","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Basic Concepts","description":"Understand Hero Health's core data model — practice groups, patients, appointments, and EHR integration — before building your first integration.","seo":{"title":"Basic concepts"}},"lastModified":"2026-04-08T14:06:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pages/api/get-started/basic-concepts","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}