Integrating Digital Health Solutions with NHS Wales: A Complete Guide for England-Based Innovators

Digital health suppliers expanding from NHS England into Wales will encounter many familiar interoperability standards, but the national infrastructure, technical interfaces and approval processes differ considerably. An application that already integrates with NHS England through the NHS England API platform, NHS Spine or other national services cannot assume that the same connectivity, credentials or integration patterns will work across the border.

In Wales, national digital health services are managed principally by Digital Health and Care Wales (DHCW), which provides the infrastructure supporting patient identification, clinical records, medicines information and communication between healthcare systems. The NHS Wales Digital Platform exposes a growing collection of these capabilities through managed APIs, providing an increasingly standardised route for authorised third-party applications to exchange information with national services.

For suppliers, the technical work involves understanding which systems hold the required information, selecting the appropriate APIs, implementing the necessary authentication and data exchange mechanisms, and designing for the operational constraints of a national healthcare environment. Access is governed by a formal onboarding process, and approval depends on the specific clinical use case, the NHS Wales organisation sponsoring the integration and the supplier’s ability to demonstrate appropriate technical, security and clinical safety controls.

The following guide explains how these integrations are structured, how suppliers obtain access and what is involved in developing, testing and operating applications that consume NHS Wales APIs.

Understanding the NHS Wales Digital Platform and Its APIs

The NHS Wales Digital Platform provides a managed interface between external applications and national healthcare services. Rather than requiring suppliers to establish individual connections with every underlying system, the platform exposes approved functionality through an API management layer. This provides a common mechanism for authenticating applications, controlling access, managing traffic and monitoring usage, while allowing the services behind the APIs to remain responsible for their respective clinical and operational data.

The platform uses Google Apigee API management technology, with interfaces exposed through the NHS Wales API Portal. The portal provides access to API documentation, technical specifications, integration guidance and the environments used during development and testing. APIs are organised into products, each with its own permitted operations, authentication requirements and availability restrictions. Consequently, access to the portal does not automatically grant access to every national service, and approval for one API does not confer permission to consume another.

Several national services are particularly relevant to digital health suppliers developing clinical applications, patient engagement platforms or healthcare integration products.

The Master Patient Index (MPI) supports patient identification and demographic matching across NHS Wales. It provides interfaces based on the Integrating the Healthcare Enterprise (IHE) Patient Demographics Query (PDQ) and Patient Identifier Cross-Reference (PIX) profiles. PDQ allows applications to search for patient records using supported demographic information, while PIX provides a mechanism for resolving identifiers assigned by different healthcare systems. These capabilities are useful when an application receives a local hospital identifier but needs to establish the corresponding national patient identity before retrieving clinical information.

The Care Data Repository (CDR) provides access to clinical information through HL7 FHIR interfaces. Published API capabilities include access to FHIR resources representing patient information, medications, allergies, observations and diagnostic data. The catalogue also includes interfaces for FHIR bundle processing and validation. The precise resources and operations available to a supplier depend on the API specification and approved use case. A FHIR endpoint should not be assumed to support every resource, search operation or write interaction defined by the wider FHIR standard.

The Welsh Care Records Service (WCRS) provides access to clinical documents from participating NHS Wales systems. Its APIs include functionality for discovering documents associated with a patient and retrieving PDF representations of selected documents. A clinical application can use these interfaces to present relevant correspondence alongside information held within its own system, subject to the permissions and coverage of the service. The document retrieval process generally involves two distinct operations: identifying which documents are available and subsequently retrieving the required content. Applications therefore need to handle situations in which a document appears in a search result but cannot be retrieved.

The Shared Medications Record (SMR) supports the exchange of medication-related information through FHIR-based interfaces. This is relevant to prescribing, medicines reconciliation and applications that require access to medication information from multiple care settings. Implementations must distinguish between different medication resources and clinical events. A medication request represents an authorisation or instruction to supply medication, whereas an administration record describes medication given to a patient. Treating these as equivalent can introduce clinically significant errors into a consolidated medicines view.

Other APIs support the NHS Wales App, including messaging, personalised settings and prescription notifications. The platform also exposes terminology and reference data services, allowing applications to work with clinical coding systems, organisation details and other standardised information. Suppliers should examine the individual catalogue entries before selecting an interface, as the published API lifecycle status, supported operations and available environments can differ between products.

For companies already working with NHS England, an important architectural consideration is how much existing integration code can be reused. Both environments use established technologies such as REST, OAuth 2.0 and HL7 FHIR, and there are opportunities to reuse transport libraries, FHIR parsers, terminology components and validation frameworks. However, NHS Wales APIs have their own endpoints, access policies, implementation profiles and operational requirements. A reusable integration framework is valuable, but it should contain distinct national adapters rather than embedding assumptions about NHS England services throughout the application.

Accessing NHS Wales APIs: Sponsorship, Onboarding and Assurance

The first practical dependency for an England-based supplier is establishing an NHS Wales organisation willing to sponsor the integration. Third-party suppliers do not independently obtain unrestricted access to national clinical APIs. The NHS Wales organisation commissioning or supporting the application must provide the appropriate sponsorship and submit the required access requests.

This means the commercial and clinical use case should be established before substantial integration work begins. The sponsoring organisation needs to understand which services the application will consume, what information will be exchanged, which users will access that information and how the proposed data flows support an agreed healthcare purpose. An application retrieving patient demographics for a clinical workflow has a different assurance profile from a product extracting large volumes of data for analytics, even if both use technologies supported by the same platform.

The initial technical design should therefore identify the required APIs at operation level. Instead of requesting general access to clinical records, a supplier might specify that its application needs to resolve an NHS number through the Master Patient Index, retrieve selected FHIR resources from the Care Data Repository and obtain clinical documents through WCRS. It should also describe the expected request volumes, data processing arrangements, user authentication model and whether clinical information will be stored within the supplier’s infrastructure.

DHCW considers the alignment of onboarding requests with its Integrated Medium Term Plan (IMTP), so the sponsoring organisation should establish the relevant programme or delivery milestone as part of preparing the application. Requests without an appropriate reference may be delayed or rejected.

The NHS Wales Digital Platform operates separate non-production and production portals, covering a set of controlled environments used throughout the delivery lifecycle. These environments are intended for different stages of development and assurance, rather than providing interchangeable endpoints.

Sandbox access is useful for examining API contracts, understanding request and response structures and validating initial client implementations. However, simulated responses cannot reproduce every characteristic of real clinical data. Production records may contain incomplete demographic information, inconsistent coding, unusual document formats or complex medication histories that are absent from synthetic test datasets. Suppliers should avoid treating successful sandbox tests as evidence that the application is ready for clinical use.

Access to the other environments is governed by additional controls. For third-party suppliers, the sponsoring NHS Wales organisation may need to arrange domain allow-listing and security review through the DHCW Operational Security Team. A valid Code of Connection may also be required before a non-NHS Wales supplier can access SIT. Environment-specific application registration, credentials and permissions should be treated as separate configuration items, with production credentials excluded entirely from non-production workloads.

The onboarding process includes technical, security and information governance assurance. The required evidence depends on the integration, but may include a Data Protection Impact Assessment, cloud risk assessment, information governance documentation, relevant security certification, penetration testing results, clinical safety documentation, test evidence and a defined operational support model. DHCW also requires appropriate arrangements for confidentiality incidents and clinical safety incident reporting, together with production testing evidence where applicable.

Suppliers should prepare these artefacts alongside implementation rather than treating assurance as an administrative activity after development. Architecture diagrams, data flow descriptions, security controls and clinical hazard assessments are more reliable when produced from the actual system design. They are also easier to maintain when changes to an API integration, hosting arrangement or data processing activity occur before deployment.

DHCW indicates that an onboarding decision may take up to 25 days, depending on the proposed solution and its design. This should not be interpreted as the total duration of an integration project. Sponsorship, architecture development, security assurance, environment access, clinical testing and production readiness all sit around that review period. Approved consumers are also subject to the platform’s API Connection Terms, and charging arrangements may apply.

Implementing Authentication, Patient Identification and Clinical Data Exchange

Once the required APIs and access arrangements have been established, the engineering work centres on building a client that can authenticate reliably, identify the correct patient, process the relevant clinical resources and respond safely to incomplete or unavailable information.

The NHS Wales Digital Platform uses different authentication arrangements across its API products. Some published endpoints use API keys, while protected services use bearer-token authorisation. The DHCW authorisation service supports a signed JSON Web Token (JWT) assertion model in which an application creates a cryptographically signed assertion and exchanges it for a time-limited access token. The authorisation service validates the assertion using the public key associated with the registered consuming application before issuing a token for subsequent API calls.

A production implementation should separate authentication from the business logic that consumes clinical information. A dedicated integration component can manage signing keys, construct the required JWT assertions, obtain access tokens and attach those tokens to outbound requests. The precise token endpoint, signing algorithm, assertion claims and audience values must be taken from the relevant NHS Wales specification, rather than copied from an existing NHS England implementation.

Private signing keys should be held in a secure secrets manager or hardware-backed key management system. They should not be stored in application source code, shared configuration files or container images. Access tokens should be cached securely for their permitted lifetime, with renewal occurring before expiry where appropriate. When multiple application requests require a refreshed token simultaneously, the authentication component should coordinate renewal so that a single expired token does not generate a burst of unnecessary authorisation requests.

Authentication failures should be diagnosed according to where they occur. A rejected JWT assertion may indicate an incorrect signing key, invalid claim, clock synchronisation problem or application registration issue. A successful token exchange followed by an HTTP 403 response from the target service may instead indicate that the registered application does not have permission to use the requested operation. Repeatedly obtaining new tokens will not correct missing API entitlements.

Application authentication also needs to be distinguished from the identity and authorisation of the person using the application. DHCW’s published API requirements specify that requests returning patient-sensitive information must include an end-user identifier, such as an email address or another agreed identifier, using the mechanism required by the relevant API. The consuming system should maintain a reliable link between the authenticated user, their organisational role, the patient being accessed and the action performed. An application-level bearer token is not, by itself, evidence that every user of that application is authorised to view every patient record.

Patient identification introduces another layer of complexity, particularly for products that integrate with both national and local systems. The NHS number is a central identifier, but Welsh healthcare systems may also assign local patient identifiers. The MPI PDQ and PIX services help applications resolve these identities, although their use requires appropriate handling of demographic ambiguity and identifier provenance.

Consider a clinical application launched from a local hospital system using a hospital-specific patient identifier. Before retrieving national documents or clinical resources, the application may need to resolve that identifier through the appropriate cross-reference interface. The resulting identifier must be associated with its assigning authority, because the identifier value alone may not be globally unique. A supplier should preserve the identifier system, identifier value and source information within its integration model rather than reducing every identifier to a single string field.

Patient-matching operations also require explicit failure handling. A demographic query might return no result, more than one plausible match or information that conflicts with the data held in the consuming application. In these circumstances, the integration should not silently choose the first returned record. Depending on the clinical workflow, the application may need to prevent further access until the identity has been reconciled or present the discrepancy to an appropriately authorised user.

For clinical information exchange, HL7 FHIR Release 4 provides a substantial part of the interoperability foundation. NHS Wales maintains implementation guidance and Data Standard Wales profiles aligned with UK Core, with adaptations for Welsh requirements. This creates opportunities for reusing an existing FHIR implementation, but suppliers should validate against the profiles and operations actually supported by the target APIs.

A FHIR Observation resource, for example, can represent a simple numerical measurement, a coded result or a more complex observation containing multiple components. Its clinical status may indicate whether the result is preliminary, final, amended or entered in error. An application displaying observations must account for these variations rather than assuming that every resource contains a single value suitable for immediate presentation.

Similar considerations apply to medication and allergy information. An empty AllergyIntolerance search result should not automatically be interpreted as a clinically verified statement that a patient has no known allergies. It may indicate that no matching resources are available through the queried service, which is a different assertion. Medication information also requires careful interpretation of status, dates, source systems and the distinction between prescriptions, dispensing events and administrations.

FHIR validation should therefore take place at the integration boundary. Incoming resources should be checked against applicable profile requirements, including required elements, supported extensions, terminology bindings and identifier constraints. Where a response is valid FHIR but contains unexpected data, the integration should preserve relevant clinical information and record the condition for investigation rather than silently discarding fields it does not recognise.

The NHS Wales terminology APIs can support consistent interpretation of coded information, including validation and lookup of clinical concepts. Applications that map national terminology into internal structures should preserve the original code and coding system alongside any local representation. This is particularly important when information may later be written to another clinical system or displayed to users in different care settings. Terminology versions should also be considered when interpreting historical records, as a code valid at the time of entry may differ from the current terminology release.

Designing for Reliability, Security and Clinical Safety

A production integration must operate safely when APIs are slow, unavailable or return unexpected information. Healthcare applications cannot assume that every request will complete successfully, that every clinical record will be complete or that an API response will always contain the information expected by the consuming workflow.

A sensible architecture places NHS Wales connectivity behind a dedicated integration layer. This component handles authentication, endpoint configuration, request construction, response parsing, terminology mapping, error classification and audit integration. It also provides a central point for controlling outbound concurrency and monitoring API performance, without requiring each application feature to implement its own connection logic.

For a cloud-hosted product, the design should document the services that process patient data, the location of those services, the network paths used to reach NHS Wales APIs and the controls protecting credentials and clinical information. Connectivity requirements may differ between APIs and environments. Suppliers accustomed to accessing NHS England systems through HSCN or other established network arrangements should not assume that those connections automatically provide the required access to Welsh national services.

Timeout and retry handling need to reflect the operation being performed. A clinician opening a patient record may require a reasonably short timeout, followed by an intelligible indication that the information could not be retrieved. A background process operating under an approved integration agreement may tolerate longer delays, provided the workflow remains safe and the API’s traffic policies are respected.

Read operations can often be retried following transient failures, but retries should use bounded exponential backoff and comply with any documented retry instructions. Write operations require greater care because a request may have completed successfully even if the response was lost. Automatically resubmitting the same operation can create duplicate records or medication events unless the API supports a suitable idempotency mechanism. Stable business identifiers, conditional operations or idempotency keys can help where explicitly supported by the relevant API contract.

The platform also imposes usage controls, including quotas and rate limits. DHCW uses expected consumption volumes during onboarding to support capacity planning, so suppliers should estimate both typical and peak API traffic before deployment. An application with 200 concurrent users may generate considerably more than 200 requests if each patient view requires several demographic, clinical and document retrieval calls. Request volume should be measured at the API operation level, with particular attention to retry behaviour and background processing.

Caching is another area where existing product architectures may require modification. DHCW’s acceptable use requirements restrict local caching of API data unless an exceptional requirement has been explicitly agreed. The general expectation is that consumers retrieve current information from the relevant API when needed, rather than maintaining uncontrolled copies of national clinical records.

A supplier whose existing product relies on periodically synchronising complete patient records into its own database should examine whether that approach is permitted for the NHS Wales use case. The distinction between caching retrieved information, retaining legitimately created application records and storing approved clinical data for a specific purpose should be established during onboarding. The presence of an API capable of returning clinical information does not grant permission to replicate the underlying dataset.

Systematic API crawling and data extraction outside the approved purpose are also restricted. Background indexing, bulk retrieval and preloading large patient populations should not be introduced without establishing that the intended activity is permitted. Where the application needs information from multiple services during a user workflow, it may be more appropriate to retrieve those resources on demand, subject to the permitted access pattern and operational constraints.

Clinical safety must be considered alongside these engineering decisions. The applicable standards include DCB0129, which addresses the manufacture of health IT systems, and DCB0160, which addresses their deployment and use by healthcare organisations. Suppliers may need to maintain clinical risk management documentation, including a clinical safety case report and hazard log, while the deploying NHS Wales organisation has corresponding responsibilities for safe implementation and use.

The clinical safety assessment should address hazards created by integration behaviour rather than focusing only on the application’s original functionality. Incorrect patient identification, delayed observations, incomplete medication lists, duplicated clinical events and loss of data provenance can all affect clinical decisions. For example, a medication reconciliation interface might successfully retrieve and display a list of medication resources even though the underlying service does not contain a complete medication history. The application needs to present the information in a way that does not imply completeness where none has been established.

Data provenance, clinical timestamps, source-system identifiers and clear unavailable-data states can reduce the risk of misleading users. Clinical information should not be presented as current merely because it was retrieved from an API a few seconds earlier; the date of retrieval and the date of the underlying clinical event represent different concepts.

Information governance requirements also influence the implementation. A Data Protection Impact Assessment should describe the purposes of processing, categories of personal data, participating organisations, retention arrangements and relevant security controls. The responsibilities of data controllers and processors must be established for the actual service arrangement. A supplier operating an application on behalf of a health board may have different obligations from a supplier determining its own purposes for processing information.

Security controls should cover encryption in transit and at rest, privileged access, credential rotation, incident management, backup protection and the handling of clinical information in logs. General application logging should not capture access tokens, signing keys or clinical payloads containing unnecessary patient information. Audit records should retain sufficient context to support investigation without becoming an uncontrolled secondary repository of sensitive data.

Suppliers should also determine the Welsh language requirements applicable to the service. For patient-facing applications, this may involve supporting English and Welsh across navigation, notifications and clinical communications. Building language support into the application’s content architecture is preferable to introducing translated interfaces after integration is complete, particularly where messages contain dynamic clinical terminology or information returned from national services.

Testing, Deployment and Maintaining NHS Wales Integrations

Testing against NHS Wales APIs should establish that the application behaves correctly under representative clinical and operational conditions. Successful requests in a sandbox are useful early evidence, but they do not demonstrate readiness for production workloads or clinically complex records.

Initial testing should verify request formatting, authentication, expected responses and handling of documented errors. This can be performed using synthetic data and controlled test credentials. As the integration progresses through the available environments, the test strategy should expand to cover interactions between services, performance characteristics, access controls and the application’s response to inconsistent or unavailable information.

Patient identification tests should include exact matches, failed matches, ambiguous demographic results and records with multiple local identifiers. Clinical resource tests should include missing optional elements, unfamiliar terminology, different clinical statuses and resources containing valid extensions. Document retrieval should be tested using empty document lists, inaccessible documents, unexpected PDF characteristics and changes to document availability between discovery and retrieval.

For medication-related workflows, test cases should distinguish active, discontinued and historical medication information, as well as different resource types representing prescribing, dispensing and administration. These scenarios are particularly valuable because an integration can pass basic schema validation while still presenting information in a clinically misleading way.

Performance testing should reflect the expected usage pattern of the actual application. Where opening a patient record triggers multiple API requests, the supplier should measure total workflow latency and request concurrency rather than assessing each endpoint in isolation. The test should also establish what happens when an underlying service becomes unavailable during the workflow and whether the application prevents unnecessary repeat traffic.

The onboarding process may require formal test evidence, conformance testing or witnessed testing for particular integrations. Results should identify the API versions tested, the environments used, relevant scenarios, defects and their resolution. Evidence should be traceable to the approved use case and clinical risk controls, allowing the supplier and sponsoring organisation to demonstrate that the deployed implementation corresponds to the system assessed.

User Acceptance Testing should involve people who understand the intended clinical workflow. A clinician using a record viewer may identify problems with chronology, terminology or information provenance that are not visible in automated integration tests. Similarly, pharmacy users may recognise that a medication-related notification is technically valid but operationally misleading. Acceptance criteria should therefore include correct interpretation and presentation of clinical information, not merely successful connectivity.

Before production deployment, the supplier should confirm that the application registration, credentials, network configuration and approved API permissions match the tested release. Monitoring, incident escalation, support contacts and rollback procedures should be in place. The implementation should also be checked against the relevant API versions, as changes to request requirements, authentication parameters or response structures can affect an otherwise functioning integration.

Once operational, monitoring should distinguish between failures originating in the consuming application, the API gateway, the authorisation service and the underlying national service. Useful measurements include request volumes, response times, timeout rates, HTTP status distributions, authentication failures and the frequency of rejected or malformed requests. Where supported, correlation identifiers should be retained so that incidents can be investigated across organisational boundaries without unnecessarily exposing patient information.

Errors should be classified according to their likely causes. An HTTP 401 response may reflect an expired or invalid token, while HTTP 403 may indicate missing access permissions. HTTP 429 generally indicates a traffic control, and a 5xx response may originate from the gateway or a downstream service. FHIR APIs may also return OperationOutcome resources containing structured diagnostic information. These details should be processed according to the API contract and used to support troubleshooting, with suitable safeguards for any sensitive content.

Operational monitoring should also consider clinically significant failures that do not produce an HTTP error. A valid response containing an empty medication list, an unexpected patient identifier or an outdated clinical observation may need further handling even though the transport request succeeded. Where feasible, the application should capture relevant data quality conditions and surface them through its support and clinical safety processes.

DHCW provides national service management arrangements, including support through the National Service Desk. The supplier’s operational model should establish who is responsible for investigating incidents, contacting DHCW, informing the sponsoring organisation and assessing any potential clinical safety consequences. These responsibilities should be agreed before production deployment, especially where the application supports time-sensitive clinical workflows.

Maintenance also needs to account for changes in API specifications, clinical terminology, authentication arrangements and the scope of the approved integration. An application authorised to retrieve demographics cannot assume that a later feature involving medications will be covered by its existing permissions. Material changes to the data accessed, processing purpose or integration architecture may require additional approval and assurance.

For companies supporting customers in both England and Wales, a maintainable implementation will usually separate national integration concerns from the product’s core clinical functionality. Shared libraries can provide common FHIR handling, HTTP transport, validation, logging and testing capabilities, while country-specific adapters implement the required endpoints, patient identification processes, terminology rules and authorisation flows.

This approach allows development teams to reuse established engineering components without assuming that NHS England and NHS Wales operate identical services. It also makes national API changes easier to isolate and test, reducing the likelihood that a modification to one integration affects another.

A supplier preparing its first NHS Wales deployment should therefore have a clearly defined clinical use case, a sponsoring NHS Wales organisation, an integration design based on the current API specifications and an assurance process that runs alongside engineering delivery. Production readiness depends on more than successful connectivity: the application must identify patients reliably, interpret clinical data correctly, operate within the agreed access restrictions and remain safe when national services or information are unavailable.

These considerations should be built into the product from the outset, allowing NHS Wales integrations to be developed and maintained as controlled clinical services rather than treated as additional endpoints attached to an existing NHS England implementation.

Frequently Asked Questions About NHS Wales API Integration

Where can developers find NHS Wales API documentation and specifications?

Developers can browse the official NHS Wales API Catalogue through the NHS Wales Digital Platform website. The API Portal provides technical documentation, available API products and integration specifications. Suppliers should consult the latest documentation for their chosen API rather than relying on older developer guides or NHS England specifications.

Can third-party suppliers publish their own APIs on the NHS Wales Digital Platform?

Yes. Digital Health and Care Wales provides an API publishing process for organisations wishing to expose services through the national platform. APIs must meet applicable design, security and documentation requirements, including an OpenAPI specification. Prospective API providers can contact the DHCW API Platform Team to discuss discovery and publication requirements.

How can suppliers check whether NHS Wales APIs are operational?

The NHS Wales API Portal provides information about the health of its API services. Suppliers can use this information when investigating connectivity problems or unexpected failures. Production incidents are handled through the National Service Desk, with major incidents supported through out-of-hours arrangements.

Can multiple developers manage the same NHS Wales API integration?

Yes. The NHS Wales API Portal supports teams that can administer registered applications. This allows suppliers to organise application management across authorised personnel rather than relying on a single developer account. Suppliers should maintain appropriate team membership and review access when staff responsibilities change.

What is the NHS Wales NIIAS Audit API used for?

The National Intelligent Integrated Audit Solution (NIIAS) Audit API enables healthcare applications to submit audit information about access to patient clinical records. It is particularly relevant to approved integration patterns where clinical data is held locally and accessed later by an end user. Suppliers should establish whether NIIAS integration is required for their specific NHS Wales application and approved data flows.