Secure Authentication with Patient Context
At the heart of the EMIS API is a strong emphasis on security and patient confidentiality. All operations occur within a Patient Session—a secure, stateful connection established using a cryptographically protected handshake process.
This handshake involves:
- Exchange of public keys via Elliptic Curve Diffie-Hellman (ECDH)
- Generation of session keys using PBKDF2
- Sequencing of calls validated through SHA256 hashed SessionHash values
Each session is uniquely bound to a patient via a PatientRelationshipId and PatientRelationshipKey, which must be securely obtained during registration. Reuse of tokens or out-of-sequence messages will result in invalidation—mitigating replay attacks.
Third parties must securely store their client and server pre-shared keys and never transmit them. Instead, validation keys derived from them are used for mutual authentication.
Core Clinical Functionality
The EMIS API exposes a wide range of clinical capabilities structured around typical patient interactions:
Appointments
Developers can:
- Query available appointments (GetAvailableAppointments)
- View existing patient bookings (GetPatientAppointments)
- Book or cancel slots via BookAppointment and CancelAppointment
Practices configure the visibility and limits of appointment slots accessible via the API, including support for telephone consultations.
Prescribing
Through the prescribing endpoints, applications can:
- Retrieve a list of repeat medications (GetMedicationCourses)
- Submit repeat prescription requests (RequestPrescription)
- Query prescription history and statuses (GetPrescriptionRequests)
- Cancel unissued prescriptions (CancelPrescriptionRequest)
All prescribing actions are subject to practice configuration, including optional patient comments.
Medical Record Access
The API allows read-only access to structured medical records including:
- Problems, consultations, medications, allergies, immunisations
- Lab results and clinical documents
Calls like GetMedicalRecordData support fine-grained access, honouring practice-set restrictions on free text and visibility per patient or cohort. Documents must be retrieved separately using GetMedicalRecordDocumentContent, which returns base64-encoded HTML content.
Registration and Account Linking
Before any patient-level data can be accessed, user registration must occur via one of two supported methods:
- PIN Document Registration – Issued by the practice and contains all necessary identifiers for account setup (RegisterWithPinDocument).
- Demographic Registration – Uses patient-provided details such as name, DOB, and postcode (RegisterWithPatientDetails). This results in a restricted account until verified in-person at the practice.
Both methods return the PatientRelationshipId and Key, enabling creation of the authenticated Patient Session.
The API also supports emergency resets of the account linkage key (ResetAccountLinkageKey) to mitigate compromised credentials.
Deployment and Versioning Considerations
API deployments across the EMIS Web estate are rolled out in stages, meaning not all practices will support the latest version at the same time. Developers are encouraged to use the GetClinicalVersionInformation endpoint with the practice’s ODS code to determine supported features.
Each schema version is backwards-compatible but not forwards-compatible—attempting to call future-version features against an older schema will fail.
Additionally, use the GetPracticeSettings and GetUserOptions endpoints to dynamically determine which services and features are enabled for a given user and practice.
Final Thoughts
Integrating with EMIS Patient Services API demands close attention to security protocols, structured workflows, and version control. With a clear understanding of the authentication model and supported clinical functions, developers can safely extend patient access to healthcare services via third-party applications.
For any integration efforts, it is recommended to use the test environment first with the provided pre-shared keys and endpoints, ensuring full compliance before going live.