Integrating with: EMIS Patient Services API

The EMIS Patient Services API offers an interface for third-party developers looking to integrate their patient facing service with clinical data held within EMIS Web. Whether you’re enabling online appointment booking, prescription requests, or secure patient messaging, the API provides comprehensive functionality through a secure, version-controlled web service.

This article outlines key considerations when integrating with the EMIS Patient Services API, including authentication, clinical operations, and deployment best practices.

EMIS Patient Services API Authentication

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.

EMIS Patient Services API 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.

EMIS Patient Services API Registration

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.

EMIS Patient Services API Deployment

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.

EMIS Patient Services API FAQs

What are common pitfalls developers face when integrating with the EMIS Patient Services API?

One of the most common issues is improper sequence handling in the patient session lifecycle, leading to invalid sessions. Another is neglecting to check for feature availability at the practice level, causing unexpected failures in live environments. It’s also vital to ensure proper handling of base64-encoded document content, particularly for document rendering.

Can I simulate all EMIS Patient Services API functionality in a test environment?

Not entirely. Certain features, like FindPractice, are restricted in test environments due to their reliance on live EMIS customer data. You can validate schema structure and expected behaviours, but some calls will intentionally fail or return mocked responses.

How should I manage EMIS Patient Services API version rollouts across different practices?

Use the GetClinicalVersionInformation endpoint at runtime to detect the API version in use at each practice. Tailor your feature set dynamically to match available functionality. Avoid hardcoding version-specific logic unless it’s strictly necessary.

Is there a preferred language or framework for building clients against the EMIS Patient Services API?

While EMIS provides WSDLs that work well with .NET tooling (e.g., svcutil), the API is standards-compliant SOAP, meaning you can integrate using any language that supports SOAP clients—Java, Python, Node.js, etc. However, attention must be given to replicating the cryptographic handshake accurately outside the .NET ecosystem.

What should I do if I suspect a session hijack or token misuse?

Immediately reset the AccountLinkageKey via the ResetAccountLinkageKey endpoint. This puts the account into a restricted state and requires in-person validation before services can resume. Also, review logs for token reuse or sequence anomalies that could indicate replay attacks.

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.