Integrating with Patient's Health Record using the REST API

Welcome to the developer documentation for Patient Health Records API. This getting started guide will help you get up and running consuming our API. For a more in depth description and information about the service it self, please go take a look at the general documentation first.

Patient's Health Record's RESTful API gives integrators a simple and standardized way to integrate with the service for sharing journal data. The metadata and format of the messages are compliant with the FHIR-standard. The REST-API is a front to an underlying SOAP solution, utilizing the ITI-MHD-profile.

Samples

Language Repository Description
.NET https://github.com/NorskHelsenett/Pasientens-journaldokumenter Native client (SimpleRequstObjectsDemo), Pasientens journaldokumenter EPJ

Testing the API

Our API is available in a test environment. It should be available in production by Q4, 2024. The test instance will not contain any sensitive data and you or your system should never send sensitive data to it.

Ping Endpoints

The API has two ping endpoints, /ping and /pingauth. /ping can be called withouth HelseID authorization, but /pingauth requires HelseID access token with DPoP.

Ping endpoint Helse ID access token DPoP Scope
/ping - - -
/pingauth Yes Yes nhn:phr/mhd/read-document

Test environment

The test environment is available at https://api.pjd.test.nhn.no.

Swagger: https://api.pjd.test.nhn.no/swagger

This environment is available from Helsenettet and from the regular Internet.

Authentication and authorization

This API uses HelseID for authentication and authorization. To use the API you will need to have a valid HelseID token with a valid scope. To configure access, use the HelseID self service portal in the test environment.

Tillitsrammeverk

This API requires the use of user login with HelseID Tillitsrammeverk. See also Information and data model

DPoP

This API requires the use of DPoP (Demonstrating Proof of Possession in the Application Layer) which is an effective mechanism that defends against token theft.

HelseID / OAuth

Before you can start testing and using our API you need to register as a client of our service with HelseID using their self-service registration. They have their own documentation on how to proceed.

Also see our HelseID self service guide for how to configure your client in selvbetjening.

  1. Use User Authentication with API access approach to access the API. Register your client with the followng details:

    • API-Access: Pasientens journaldokumenter
    • Audience: nhn:phr
    • Scope(s):
      nhn:phr/mhd/read-documentreferences and/or
      nhn:phr/mhd/read-documentreferences/kjernejournalforskriften and/or
      nhn:phr/mhd/read-document (All are currently default in selvbetjening)

    Example project from HelseID for User Authentication with API access with DPoP apporach

When your client is set up to use HelseID you should provide the negotiated OAuth token in the HTTP header Authorization as a DPoP token on all requests to our service. You also need to provide a 'DPoP' header with the DPoP token. Example headers:

Authorization: DPoP bearer token

DPoP: DPoP proof token

API Specification

The inner details on our API is documented using OpenAPI specification. The details are available in our user interface representation of the specification here.

ITI.MHD profile

The API has the following endpoints which is compliant with transactions in the Mobile access to Health Documents (MHD) Profile at https://profiles.ihe.net/ITI/MHD/.

The inner details on our API is documented using OpenAPI specification. The details are available in our user interface representation of the specification here.

HTTP method API endpoint Scope ITI.MHD transaction
POST /R4/fhir/DocumentReference/_search nhn:phr/mhd/read-documentreferences or nhn:phr/mhd/read-documentreferences/kjernejournalforskriften Find Document References (ITI-67)
GET /mhd/document nhn:phr/mhd/read-document Retrieve Document (ITI-68)

Due to security restrictions it's not possible to call the /R4/fhir/DocumentReference endpoint with HTTP GET method

Errors

The API returns errors as FHIR OperationOutcome resources.

Caching

For now, the get document references endpoint caches the result for 3 minutes in order to facilitate fast server paging.

Test patients and test health personell

Our internal document registry in Norsk Helsenett in the test environment is preloaded with some default test patients which has some patient health records.

Furthermore, the test environment will query other Cross Community Gateways in the test environments of connected registry servers.

Test patients

Patient.identifier (NIN) Patient Name Example document Location
13116900216 LINE DANSER Brev - test CDA.pdf NHN document registry
12119000465 Malin Fos Bogen Various
15076500565 Roland (Kith) Gundersen Various
23077200290 Else Nett Various

Test health personell

NIN HPR Health personell name Authorization
13116900216 565501872 GRØNN VITS Lege
13116900216 565505933 KVART GREVLING Lege
13116900216 565512796 VIRKELIG KJELTRING Sykepleier
13116900216 565501872 LIVSTRETT BEVER Vernepleier
13116900216 DIREKTE HEI Ikke helsepersonell
13116900216 VEIK LOGARITME Ikke helsepersonell
13116900216 HYPPIG AVTALE Ikke helsepersonell
23075821492 Benedicte Geiraas
22047800106 Truls Blix

more example data to come

Examples

Examples on how to use this API

Find Document References

Endpoint: HTTP POST /R4/fhir/DocumentReferences/_search

The Find Document References transaction is used to find DocumentReference Resources that satisfy a set of parameters. While patient.identifier and status are the only required parameters, the others are optional.

Scopes

The endpoint requires one of the following two scopes. It's not possible to use both scopes in the same request.

Scope Lovverk Description
nhn:phr/mhd/read-documentreferences Helsepersonelloven p. 45 No access basis header parameter. No filtering according to Kjernejournalforskriften.
nhn:phr/mhd/read-documentreferences/kjernejournalforskriften Kjernejournalforskriften Access basis header parameter is required. Filtering according to Kjernejournalforskriften.

Filtering according to Kjernejournalforskriften

If using the second scope.

Category Dokumentgruppe Varighet på visning i kjernejournal Eksempler på dokumenter
A00-1 Epikriser og sammenfatninger Ubegrenset Epikriser etter innleggelse, poliklinikk m.m.
C00-1 Prøvesvar, vev og vesker 1 år Medisinks biokjemi, patologi m.m.
D00-1 Organfunksjon 5 år Ultralyd av hjerte, spirometri m.m.
E00-1 Bildediagnostikk 5 år Radiologi, ultralyd m.m.
I00-1 Korrespondanse 1 år Henvisninger

Example

Simple POST to retreive all document references for LINE DANSER

Example POST Body

POST api.pjd.test.nhn.no/fhir/DocumentReference/_search	  
Host api.pjd.test.nhn.no
Content-Type: application/x-www-form-urlencoded
Accept: application/fhir+json; fhirVersion=4.0
Authorization: DPoP <DPoP authorization bearer token>
DPoP: <DPoP proof token>

patient.identifier=13116900216&status=current

Header Parameters

Header parameter Required? Possible values
hit-access-basis Only for Kjernejournalforskriften UNNTAK, SAMTYKKE, FORHOYET_SAMTYKKE, AKUTT, FORHOYET_AKUTT

Query Parameters

See ITI-67 for full details

Query parameter Required? Type Description
patient.identifier required token Patient identifier (NIN)
status required token The status (availabilityStatus) of the DocumentReference Resource
author.given string Given name of the author person
author.family string Family name of the author person
category token General classification (classCode) of the DocumentReference Resource
creation DateTime Specifies a search against the DocumentReference.content.attachment.creation
date The time when the DocumentReference was created
event token Specifies the main clinical acts (eventCodeList) documented by the DocumentReference Resource
facility token The kind of facility found in DocumentReference.context.facilityType (healthcareFacilityTypeCode)
format token The format (formatCode ) of the DocumentReference Resource
identifier token An identifier for this DocumentReference and/or the contained document. The search results represent the results of a search on DocumentReference.masterIdentifier and DocumentReference.identifier
period date Represents the time of service that is being documented by the DocumentReference. This query parameter represents from/to parameters for the serviceStartTime and serviceStopTime of the Document Entry
related reference Represents other identifiers (referenceIdList) associated with the DocumentReference Resource
security-label token The security labels (confidentialityCode) of the document referenced by DocumentReference Resource
setting token The specific practice setting (practiceSettingCode) of the DocumentReference Resource
type token The specific type of the DocumentReference resource or in Document Sharing nomenclature, the typeCode of the Document Entry

Response

The endpoint returns a FHIR bundle according to ITI-67.

Response validation

The structure of the response has been validated with Matchbox.health validation service and should be compliant with FHIR R4 and ITI-67.

Retreive Document

Endpoint: HTTP POST /mhd/document

The Retrieve Document [ITI-68] transaction is used by the Document Consumer to retrieve a document from the Document Responder.

Parameters:

documentUniqueId, homeCommunityId and repositoryUniqueId is returned from the request to Find Document References.

Parameter Type Description
hit-patient-pid Header Patient identifier (NIN), required to generate SAML assertion
documentUniqueId Query Global identifier for a document in Cross-enterprise document sharing for healthcare
homeCommunityId Query Identifier for participant's home community in Cross-enterprise document sharing for healthcare
repositoryUniqueId Query Unique ID for the document repository in Cross-enterprise document sharing for healthcare

Example GET request

GET api.pjd.test.nhn.no/mhd/document?documentUniqueId=1.2.840.4711.815.1.30112023.1&repositoryUniqueId=2.16.578.1.12.4.1.7.1.2.12.1.1.2.31&homeCommunityId=urn:oid:2.16.578.1.12.4.1.7.1.2.12.1.1
Host api.pjd.test.nhn.no
Accept: application/pdf; 
hit-patient-pid: 13116900216
Authorization: DPoP <DPoP authorization bearer token>
DPoP: <DPoP proof token>

Return value: The document itself with its associated content type (e.g. application/pdf or application/xml).

NOTE: Currently the API cannot return a FHIR json bundle of type document with application/fhir+json, with all the content encoded as FHIR resources.