HL7 Norge
FHIR Implementation Guide for the Norwegian Municipal Sector
Shared starting point for understanding and consistent use of FHIR in municipal health and care services.
Norwegian

FHIR Implementation Guide for the Norwegian Municipal Sector
0.3.0 - Norway flag

FHIR Implementation Guide for the Norwegian Municipal Sector - Local Development build (v0.3.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

API

This page describes API principles and documentation requirements for this IG.

What This Page Controls

The API page controls:

  • how searches are linked to prioritized use cases
  • which API requirements are normative in v0.3.0
  • which expectations apply to CapabilityStatement

What Matters Most In v0.3.0 (Guidance)

  • API use should be use case driven: clinical and operational needs are linked to concrete FHIR searches.
  • Clients retrieve patient data using standard FHIR REST/search.
  • Planned contacts should use Appointment where they are shared before completion. Completed contacts should still use Encounter.
  • "No data found" is interpreted as a valid empty result, not automatically as an error.
  • v0.3.0 is a pragmatic minimum without new custom operations.
  • v0.3.0 primarily describes read and search in a FHIR API.
  • Full support for create, update and documentation write-back is not part of the normative minimum in this version.
  • This is aligned with ongoing national work in the Norwegian Association of Local and Regional Authorities (Kommunesektorens organisasjon, KS) and the Norwegian Health Network (Norsk helsenett, NHN), where municipal interoperability services and modernized Welfare Technology Hub (Velferdsteknologisk knutepunkt, VKP) are moving towards API-based information services.

Prioritized Minimum Resource Set (Guidance)

  • Patient
  • Encounter
  • EpisodeOfCare
  • CarePlan
  • DocumentReference
  • ServiceRequest

These resources should use the municipal profiles where such profiles are defined: no-kommune-ServiceRequest, no-kommune-Encounter, no-kommune-EpisodeOfCare and no-kommune-CarePlan.

Recommended supporting resource when planned contacts are exposed:

  • Appointment

Planned contacts should use no-basis-Appointment where the national base profile is applicable. This does not make a separate no-kommune-Appointment profile part of the v0.3.0 minimum.

Next wave, not normative minimum in v0.3.0:

  • MedicationStatement
  • AllergyIntolerance
  • Condition
  • Observation

Observation is especially relevant as a next step because National Early Warning Score 2 (NEWS2) measurements, Patient's measurement data (Pasientens måledata, PMD) and modernized VKP all point towards structured sharing of measurements and assessments.

The list concerns future API support. The KPR example already uses the standard Observation and Goal resources as supporting resources.

Relation To PMD/VKP (Normative Boundary)

  • This IG SHALL NOT define competing endpoints, profiles or bindings for Patient's measurement data (PMD) or VKP.
  • Measurement data shared through PMD/VKP SHOULD follow the PMD/VKP information model and API documentation.
  • Municipal APIs MAY refer to relevant Observation resources as supporting data, but SHOULD document whether measurements are retrieved from a local journal, VKP, PMD or another source.
  • When the same user interface uses both this IG and PMD/VKP, the CapabilityStatement or service documentation SHOULD describe which resources come from which service.

Relation To Trust Framework And Security (Guidance)

This IG describes FHIR resources, profiles and search patterns. It does not by itself decide whether a user or system is allowed to access a patient's information.

Implementations SHOULD document the surrounding trust and security model, including authentication, authorization, legal basis for access, organization trust, logging and follow-up/audit. In a Norwegian cross-organizational setting, this will often be related to HelseID, OAuth/OpenID Connect and the national trust framework. Such requirements belong in the API/security documentation and CapabilityStatement, not as separate municipal data profiles.

FHIR references between resources SHALL NOT be interpreted as proof that the requesting party has access rights to all referenced resources. Access control is evaluated by the service and its trust framework.

See also Use cases for full context and more examples.

Prioritized use case Resources Search example
Discharge and follow-up EpisodeOfCare, CarePlan GET [base]/EpisodeOfCare?patient=Patient/[id]&status=active and GET [base]/CarePlan?subject=Patient/[id]&status=active
Planned follow-up ServiceRequest, Appointment, Encounter GET [base]/ServiceRequest?subject=Patient/[id]&status=active, GET [base]/Appointment?patient=Patient/[id]&date=ge[YYYY-MM-DD]&status=booked and GET [base]/Encounter?patient=Patient/[id]&date=ge[YYYY-MM-DD]
Service need and decision DocumentReference, ServiceRequest GET [base]/DocumentReference?subject=Patient/[id]&type=[code] and GET [base]/ServiceRequest?subject=Patient/[id]&status=active

The search examples are intentionally standard FHIR searches. Implementations SHOULD document if they require _profile, custom search parameters or additional filters.

Relationship To Open Aidn (Guidance)

Open Aidn is a concrete example of a vendor API for municipal integrations. The documentation was reviewed on 2 October 2026. It describes the endpoints, searches and OAuth 2.0 scopes supported by Open Aidn. It also states that the service currently uses selected fields from the FHIR R4 base resources and that formal Aidn profiles may be published later.

Open Aidn Relationship to the municipal IG
Patient Open Aidn refers to no-basis-Patient where applicable. This supports using no-basis as the Norwegian foundation, while actual field support still needs to be checked against the service.
EpisodeOfCare and Encounter These resources overlap directly with the municipal profiles. Open Aidn currently describes service type in EpisodeOfCare.type and Encounter.type. The municipal IG uses Encounter.type for contact type and Encounter.serviceType for service context, and does not assume that a service code is appropriate as an episode type. This difference needs to be resolved in an implementation mapping.
Observation Can make assessments and measurements available as supporting data. The municipal IG uses standard Observation in its examples but does not define a dedicated profile in v0.3.0.
Task Open Aidn uses Task for planned work. This fits the option for CarePlan.activity.reference to reference a Task, but does not replace ServiceRequest when the shared information is a request or order.
Search and access Open Aidn documents POST .../_search, municipality-specific activation, and its own scopes and search parameters. These are part of the Open Aidn service contract, not general requirements in the municipal IG.

The Open Aidn documentation should therefore be used for integrations with Aidn, while this IG describes shared semantics across vendors. The documentation reviewed does not list endpoints for ServiceRequest or CarePlan; direct support for all four municipal profiles therefore cannot be assumed. Custom search parameters and actual resource support should be listed in the service's CapabilityStatement and any SearchParameter resources.

Access to KPR functional assessments (guidance)

When a request or plan references a functional assessment, the recipient needs an agreed way to retrieve it with appropriate access. Follow reasonReference and supportingInfo references to obtain the specific assessment basis, for example GET [base]/Observation/example-kpr-function. A later assessment does not replace this basis.

If the service supports assessment searches, standard Observation search can be used. Example for personal hygiene in August (URI-encoded separator between system and code):

GET [base]/Observation?patient=Patient/[id]&code=urn:oid:2.16.578.1.12.4.1.1.9111%7C7&date=ge2026-08-01&date=lt2026-09-01

Document supported searches, sorting and pagination. Determine the latest assessment per functional domain and clinical time, accounting for status and absent results. A single latest result across all domains is not a complete assessment. Do not infer the patient's function from an empty search result.

The IG's CapabilityStatement template does not cover Observation. A service sharing functional assessments needs to document supported reads, searches and access in its own documentation and CapabilityStatement. Journal data is not automatically routed through PMD/VKP.

Normative Main Points

  • Each prioritized use case SHALL have at least one documented recommended search pattern in the IG.
  • Services SHOULD represent a valid empty search result as an empty Bundle.

Empty Search Results And Error Responses

  • A successful search with no matches SHALL return HTTP 200 with Bundle.type=searchset and no entries in entry.
  • Clients SHOULD treat such a response as a valid empty result.
  • Request errors, such as invalid parameter format, SHALL return 4xx with OperationOutcome.

Boundary For Write-Back And Documentation

  • v0.3.0 SHALL NOT be understood as a requirement for full support for create, update or delete of resources.
  • v0.3.0 SHALL NOT be understood as a complete specification for writing documentation from external systems into municipal EHRs.
  • If an implementation supports write-back or documentation submission, this SHOULD be described explicitly in separate service documentation and in CapabilityStatement where relevant.

API Versioning

  • API versioning SHALL follow SemVer principles (MAJOR.MINOR.PATCH).
  • MAJOR changes, meaning breaking changes, SHALL be published so clients can distinguish old and new API versions, for example by a separate URL path.
  • MINOR/PATCH changes SHALL be backwards compatible for existing clients.
  • API version and FHIR version SHALL be treated as separate versioning tracks.

Search, Operations And CapabilityStatement

  • The API SHALL document which searches are supported per resource.
  • The API SHALL document which central FHIR searches are not supported.
  • The API SHALL document which operations are supported, or state that no custom operations are supported.
  • Custom search parameters SHALL be described as SearchParameter and listed in CapabilityStatement.
  • Custom operations SHALL be described as OperationDefinition and listed in CapabilityStatement.
  • Any deviations from standard FHIR REST behavior SHALL be documented explicitly.
  • If an implementation supports booking, rescheduling, appointment response or other workflow operations beyond read/search, these operations SHALL be documented explicitly and listed in CapabilityStatement.

Search By National Identifier (FNR/DNR)

  • Search by national identifier SHOULD use POST [base]/<Resource>/_search to reduce the risk of sensitive information being logged in URLs.
  • If a service requires POST for such searches, this SHALL be stated in CapabilityStatement.
  • The requirement SHOULD also be documented clearly in this IG for each relevant resource (Patient, Person, RelatedPerson).

References