EMIS Partner API Integration: From Legacy COM to Modern HTTP

For many healthcare software teams, EMIS integration has historically meant working close to the desktop. The older Partner API model depended on a locally installed COM DLL, practice-level activation, Windows-specific assumptions and a style of integration that made sense in a different era of clinical IT. It worked, and many useful systems were built on it, but it also shaped product architecture in ways that are now difficult to defend: local dependencies, brittle deployment steps, support-heavy onboarding, constrained hosting options and a constant need to design around the machine where EMIS Web was running.

The new EMIS Partner API changes the centre of gravity. The most visible difference is technical: standard HTTP endpoints instead of a local COM component, OAuth/OIDC tokens instead of the older activation model, and an OpenAPI-described interface that can be called from modern software stacks. The deeper difference is architectural. An EMIS Partner API integration is no longer just a question of calling a function and parsing a response. It requires clear thinking about token context, user identity, patient context, appointment and clinical-record permissions, error handling, audit, hosting and clinical safety.

This shift is welcome, but it should not be misunderstood. The new Partner API is not a clean-sheet rewrite of every clinical workflow into neat REST resources. Much of the language, function naming and payload shape still reflects the legacy EMIS Partner API and EMIS Open world. That is deliberate. It gives existing suppliers a migration path and avoids forcing every partner to remodel years of working integration logic at once. The result is a hybrid: modern transport and security wrapped around a familiar set of capabilities. A good integration treats it as exactly that.

EMIS Partner API integration and the move away from legacy COM

The legacy COM-based integration model placed the partner application close to the clinical workstation. In many cases, this encouraged desktop-first thinking even where the product itself wanted to become web-based, cloud-hosted or service-oriented. Developers had to think about installation state, DLL availability, local machine configuration, activation, permissions and the behaviour of calls made from a client environment they did not fully control. Support teams then inherited the consequences: one practice worked, another did not; one workstation had the right component, another needed intervention; one deployment was blocked by policy, another was broken after an update.

Moving to HTTP removes a large part of that friction, but not all of it. The practical gain is that a partner can call the EMIS Partner API from a conventional backend service, using ordinary HTTP clients in C#, TypeScript, Python or any other suitable language. The integration becomes easier to test outside a clinical desktop, easier to observe, easier to wrap in retry and logging logic, and easier to maintain within a normal software delivery process. This is a material change for product teams that have spent years keeping Windows integration code alive because there was no better route into EMIS workflows.

There is also a staffing benefit, although it is rarely discussed plainly. COM-based healthcare integration tends to require people with a mixture of legacy Windows knowledge, clinical-system familiarity and patience with local deployment issues. Those people are valuable, but they are scarce. HTTP and OAuth are not trivial, yet they are mainstream. A team can bring in engineers who already understand bearer tokens, OpenAPI specifications, request tracing, secrets management, automated testing, CI/CD and backend service design. The EMIS-specific knowledge remains necessary, but it sits on top of familiar foundations.

The naming of the new Partner API is worth reading carefully. Several functions retain legacy-style names such as GetMedicalRecord, GetBookedPatients, GetAppointmentSessions, BookAppointment, CancelAppointment, GetMatchedPatients and FileRecord. These are not resource names in the pure REST sense. They are operation names exposed over HTTP. That may offend purists, but for migration it is useful. If an existing product already understands the business meaning of those calls, the work becomes less about rediscovering what the integration does and more about changing how it is called, authenticated, monitored and supported.

This is where some migration projects will go wrong. Teams may treat the change as a thin transport swap: replace COM calls with HTTP calls, keep the rest of the application more or less intact, and move on. That may be enough for a narrow proof of concept, but it misses the main engineering opportunity. The move to the EMIS Partner API is a chance to isolate EMIS connectivity into a dedicated integration layer, remove clinical-system assumptions from product code, introduce proper test doubles, centralise audit, and design for token expiry, permissions and API failure from the start. In a clinical product, the boring parts of the architecture are the parts that keep the system safe.

EMIS Partner API migration: what changes in practice?

The move from the legacy EMIS Web Partner API model to the modern EMIS Partner API is not only a change in transport. It changes where the integration runs, how access is authorised, how support teams diagnose faults and how product teams design safe clinical workflows.

The table below summarises the practical differences that matter most when planning an EMIS Partner API integration, especially for suppliers moving away from older EMIS Open, COM DLL or desktop-dependent architectures.

EMIS Partner API authentication, user context and patient launch flows

Authentication is the part of EMIS Partner API integration that deserves more attention than endpoint mapping. With the old model, a lot of context came from the local EMIS environment and activation arrangements. With the new model, access is mediated through OAuth/OIDC flows and transparent JWTs. Those tokens carry claims that affect what the application can do and on whose behalf it is acting. Treating the token as a mere string to be attached to requests is a mistake.

There are two broad access models to understand. A backend service may use the Client Credentials Flow, receiving an access token for the application itself. This suits certain server-side integrations, especially where no individual user is present and the partner service is acting as an authorised application. The alternative is a user-context flow, typically Authorization Code with PKCE, where the partner application acts on behalf of an EMIS user. Some APIs may require user-restricted tokens, so a product cannot assume that machine-to-machine access will cover every use case.

This distinction shapes the product design. A background job that checks for changed patients, processes appointment data or performs an authorised service-level operation may fit an application-restricted model if the API and assurance scope allow it. A desktop-launched application that opens in the context of a clinician and a specific patient is different. It needs to preserve user intent and patient context. In that case, EMIS can launch the partner application using a registered launch URL, pass a launch identifier, and allow the application to complete an Authorization Code with PKCE exchange. The resulting ID token can include patient context, user information, organisation details and authorisations.

The context-management flow is particularly relevant for products used inside consultations. A clinician should not have to search again for the patient they already have open, nor should the partner system infer patient identity through unreliable screen scraping or manual entry. A properly implemented launch flow gives the partner application a cleaner route: receive launch context, complete the auth flow, decode the ID token, read the patient identifiers and then call the relevant Partner API endpoints with the access token. The clinical experience is better, but the engineering requirement is stricter. The application must validate state, protect the code verifier, handle redirects correctly, store tokens carefully and avoid leaking patient context into logs or analytics tools.

The token content also changes how authorisation is enforced inside the partner product. If the token contains an authorisations array, organisation identifiers, user details and role information, the application can make more informed decisions before it calls the EMIS API. It can also produce better audit records. A useful audit trail should not simply say that an endpoint was called at 10:03. It should record which product tenant, which organisation, which user context, which patient identifier, which operation, which permission family, which correlation ID and what the result was. That becomes important when investigating clinical incidents, support cases, data protection queries or unexpected user behaviour.

Token expiry should be treated as routine, not exceptional. Access and ID tokens are short lived. Refresh behaviour, re-authentication and failure states need to be designed into the user journey. A clinical desktop app should not crash into a technical error because a token expired while the user was reading a record. A backend job should not silently stop synchronising because its token handling was written for a demo. The application needs predictable states: authenticated, expired but refreshable, expired and requiring user action, unauthorised for the requested operation, and unavailable because EMIS or the identity provider cannot be reached.

One subtle risk is confusing authentication success with clinical permission. A valid access token does not mean every endpoint is available, and a user-context token does not mean every patient or operation is appropriate. The product should still enforce its own rules around purpose, role, organisation, patient selection and user action. The EMIS Partner API will enforce its own security boundary, but the partner system remains responsible for using access safely and proportionately.

EMIS Partner API capabilities for appointments, patient matching and medical records

The Partner API capability set is broad enough to support several classes of healthcare software, but it is not a general-purpose database interface into EMIS. The useful way to think about it is by workflow area: appointment operations, patient matching and demographics, clinical record retrieval, attachment handling, and controlled record updates. Each area has its own risks.

Appointment integration is one of the clearest opportunities. The API exposes calls for appointment configuration, appointment sessions, slots for a session, booked patients, arrived patients, sent-in patients and patient appointments. It also exposes write operations such as booking an appointment, cancelling an appointment, adding slot comments, setting appointment status, setting slot notes and changing slot type. That gives suppliers enough to build patient booking journeys, reception tools, triage allocation, waiting room views, capacity dashboards and operational workflow products. The difficult part is not listing available slots. It is interpreting local configuration correctly and avoiding behaviour that creates pressure on practice appointment books.

The appointment configuration call is more significant than it first appears. Appointment books are not standardised in the way product teams often wish they were. Slot types, session holders, sites, staff holidays, practice holidays and local operating rules vary between organisations. A naive booking integration assumes that a slot is just a unit of time. A better integration treats appointment configuration as a local contract. It respects session holder rules, filters by appropriate slot type, limits the time window of queries and avoids repeated large searches that place unnecessary load on the clinical system. This is not only a performance issue. It affects patient safety and practice trust.

Booked-patient and waiting-room style calls need similar care. Some appointment-list responses may indicate the presence of alerts in the record, but those alerts may not be suitable for display to patients. An integration that powers reception screens, call boards or patient-facing check-in flows must separate operational data from clinical-sensitive data. Developers should not simply render whatever comes back from the API. They need a display model designed for the audience. What a receptionist can see, what a clinician can see and what a patient can see are different things.

Patient matching is another area where technical success can hide clinical risk. Endpoints such as GetMatchedPatients, GetChangedPatients, GetChangedPatientsMR, GetPatientSequence, GetPatientDemographics and GetPatientSearches support identity lookup, synchronisation and patient list workflows. These are useful for recall tools, cohort management, document workflows and applications that need to keep an internal patient index aligned with EMIS. But matching should never be treated as a casual string comparison exercise. NHS number, EMIS patient number, EHR partner identifiers, GUIDs, demographics and context-provided identifiers each have different properties. A safe system records which identifier was used, how confident the match was, and what happens when the match is ambiguous.

Medical record access is the most powerful part of the API and the part most likely to expose weak product thinking. Calls such as GetMedicalRecord, GetCodedRecord, GetConsultation, GetEvents, GetMedicationIssues, GetAttachments, GetAttachmentsV2 and GetBase64AttachmentData can support clinical summarisation, document preparation, decision support, review tools, record navigation and reporting-style workflows. The schemas suggest a rich EMIS Open-style clinical payload, including consultations, coded entries, medication, pathology, referrals, problems, alerts, attachments and related clinical structures. That richness is useful, but it comes with responsibility. Pulling a full medical record to answer a narrow question may be technically easy and still be poor information governance.

Attachment handling needs its own design. The attachment list and the base64 attachment-data call imply a two-stage process: discover available attachments, then retrieve the selected binary content. This is a sensible structure, but it means the partner product must decide which files are needed, how long to retain them, where to store decoded content, how to scan or process it, and how to dispose of it afterwards. Attachments are often where the mess of real clinical records lives: scanned letters, referral documents, historic PDFs, images, correspondence and sometimes content with unexpected sensitivity. A mature integration handles attachment metadata separately from attachment content and does not download everything “just in case”.

Write-back capability is present but controlled. FileRecord, UpdateAttachment and UpdateConsultationVisibility should not be read as permission to treat EMIS as a fully writable datastore. Filing into the record is a clinical act, even if it is performed by software. A safe product needs clear authorship, provenance, coded versus free-text decisions, review flows, failure handling and a way for users to understand what will be written before it is written. If a document is filed twice because of a retry bug, that is not a harmless duplicate database row. It becomes part of the patient record.

Designing a production-ready EMIS Partner API integration architecture

A production integration should normally sit behind a dedicated EMIS integration service rather than being scattered through the main application. This service can own token handling, request construction, endpoint-specific clients, response mapping, error translation, audit logging and rate-conscious querying. The rest of the product then depends on internal domain models rather than raw EMIS payloads. This separation makes the system easier to test, easier to change and easier to support when EMIS behaviour differs between environments or when a practice has unexpected configuration.

The first responsibility of that service is authentication. It should support the flows the product actually needs, not every theoretical flow. For a backend-only use case, that may mean secure handling of client credentials, environment-specific secrets and token caching. For a desktop launch or user-context product, it may mean PKCE, redirect handling, state validation, token storage and extraction of patient context from the ID token. In both cases, the integration should assume tokens expire, scopes differ, environments are separate and credentials can be rotated. Secrets should not live in desktop clients unless the flow explicitly supports public-client behaviour.

The second responsibility is endpoint modelling. Raw endpoint names can remain visible inside the integration layer, but they should not leak across the product. Internally, the product should ask for concepts such as appointment availability, booked appointments, patient demographics, record summary, medication issues or attachment content. The integration service can then decide which EMIS endpoint is required, what parameters are needed, what headers must be sent, how to format dates, how to limit query windows and how to map the response. This protects the rest of the product from legacy naming and gives engineers one place to handle versioned calls such as GetBookedPatientsV2 or GetPatientAppointmentsV2.

Error handling deserves more care than a simple status-code switch. The newer API uses standard HTTP status codes, but legacy-style outcome information may still appear in error responses to help migration. A robust integration should preserve both. HTTP status tells the platform what happened at the transport or API boundary: bad request, unauthorised, not found, unsupported media type, internal error. The legacy outcome may explain the clinical-system side of the failure in a way existing support teams recognise. The product should translate both into meaningful user-facing messages and support-facing diagnostics. A clinician does not need to see a raw 500. Support may need the endpoint, parameters, correlation ID, token type, organisation and returned outcome.

Observability is not optional. EMIS integrations often fail in ways that are specific to context: a single organisation, a particular user role, a date range, a slot type, a patient with unusual record structure, a document with duplicate names, a configuration difference between test and production. Logs need to be detailed enough to investigate without exposing unnecessary patient data. Metrics should show request volume, latency, failure rates, token refresh failures, permission failures, endpoint-specific error spikes and unusually heavy queries. For appointment endpoints, monitoring query-window size is especially useful because an integration can behave acceptably in testing and then place heavy load on a live system through repeated broad searches.

Testing should be split into several layers. Unit tests can verify request building, response parsing and error translation. Contract-style tests can confirm assumptions against the Swagger and any test environment behaviour. Integration tests can exercise authentication, token expiry and representative endpoint calls. Clinical workflow tests should cover the awkward cases: no matching patient, multiple matches, cancelled appointments, slot already taken, expired launch context, missing permission, duplicate attachment names, unexpected coded data, empty record sections and write-back failure after partial user action. Those cases are where unsafe products reveal themselves.

Data minimisation should be designed into the service rather than added later. If a workflow only needs appointment slots, it should not fetch clinical records. If it only needs attachment metadata, it should not retrieve base64 content. If a user opens a patient-context app, the product should use the context rather than prompting for another search unless there is a reason. Retention rules should be explicit. Clinical data copied out of EMIS into the partner system does not become harmless because it is cached for convenience.

The front end should also reflect the constraints of the integration. Users should understand which organisation and patient context they are operating in. If the app was launched from EMIS with a patient in context, the UI should make that visible enough to prevent wrong-patient work. If the token no longer permits an action, the system should explain the permission problem rather than implying a technical failure. If a write-back action is pending, the UI should show exactly what will be filed or updated. For clinical systems, a good interface is not one that hides complexity completely; it is one that reveals the right complexity before a risky action.

Migrating from EMIS Open and COM DLL integrations to the modern EMIS Partner API

A sensible migration starts with an inventory, not with code. List every current COM call, the product feature that uses it, the parameters passed, the response fields consumed, the permissions assumed, the clinical user involved, the patient identifiers used, the frequency of the call and the failure behaviour. Many older integrations call more than they need. Some retrieve a large record and use three fields. Others poll appointment data too broadly because it was simpler at the time. Migration is the chance to reduce that surface.

After the inventory, map each current function to the new Partner API endpoint and classify it by workflow: appointment read, appointment write, patient matching, demographics, clinical record read, attachment retrieval, record filing or record update. This creates a useful view for assurance and engineering. It also exposes gaps. Some legacy behaviours may not map directly. Some may require user-restricted tokens rather than application-restricted tokens. Some may need a different launch flow. Some may no longer be appropriate because the old product design depended on local assumptions that the modern API deliberately removes.

The next step is to decide whether the product is being migrated or merely reconnected. Reconnecting means keeping the existing architecture and replacing the integration mechanism underneath. It can be faster, but it often preserves poor boundaries. Migrating properly means building a new integration layer, introducing modern token handling, cleaning up data models, retiring local deployment assumptions and improving audit. The right answer depends on commercial pressure, contract commitments and risk. For a product with a long future, reconnection alone is usually a false economy.

Parallel running is useful where it is allowed and practical. If the old COM integration and the new HTTP integration can both be exercised in a test environment, compare outputs for the same patient, appointment book and workflow. Differences should be documented rather than hand-waved. Some differences may be harmless format changes. Others may indicate a missed parameter, a date interpretation issue, a permission difference or a response version difference. This is especially relevant for medical record data, where small mapping errors can produce misleading clinical summaries.

Date handling is a common migration trap. Legacy systems and modern APIs may express dates, time windows and filters differently. Appointment endpoints can have explicit search limits and recommended narrow windows. A product that previously used broad local calls should not simply reproduce those windows over HTTP. It should query for the smallest useful range, cache carefully where appropriate, and refresh only when the workflow requires it. This reduces load and often improves the user experience.

Patient identifiers need deliberate handling during migration. Existing products may store EMIS patient numbers, NHS numbers, local IDs or older partner identifiers. The modern context flow may provide multiple identifiers in the token’s patient context. The migration should define a canonical internal patient reference strategy and record the source of each identifier. A product that cannot explain how it matched a patient should not be writing back to that patient’s record.

Write-back migration should be treated as a separate workstream. Reading data incorrectly can mislead users; writing data incorrectly can alter the clinical record. Any use of FileRecord, attachment update or consultation visibility update should have its own acceptance criteria, audit design, duplicate prevention, retry rules, user confirmation and rollback thinking. In many systems, it is safer to migrate read capability first and add write-back only after the new EMIS integration layer has proved stable.

Support teams should be brought into the migration early. They know which failures occur in real practices, which configuration differences cause confusion and which error messages lead to long support calls. The new API will change the support model. Instead of asking whether the COM DLL is installed and activated, teams will ask about token type, scopes, launch context, application ID, environment, organisation, endpoint, HTTP status and returned outcome. Support tooling should reflect that before the first pilot site goes live.

The final migration decision is timing. It is tempting to wait until the old route is near retirement, especially for products with a stable installed base. That creates a rushed project later, usually under less favourable conditions. A measured migration gives the team time to understand OAuth, context management, endpoint behaviour, assurance questions and production support. It also gives product managers time to improve workflows that were constrained by the old integration model.

The move from legacy COM to the modern EMIS Partner API is therefore not just an infrastructure update. It changes how partner software is built, deployed, authenticated and supported. It gives teams a more maintainable way to work with EMIS data and workflows, but it also asks for more disciplined engineering. The best integrations will not be the ones that call the most endpoints. They will be the ones that call the right endpoints, in the right context, with the least data needed, with clear audit, predictable failure behaviour and a careful respect for the clinical record.