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.

Testing the API

Our API is available in a test environment. It should be available in production by may, 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. DPoP is currently not needed for /pingauth.

Test environment

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

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

NOTE: The test environment uses a staging SSL certificate from Let's Encrypt. Make sure you trust it from your test code and manually when visiting in the browser.

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-document (Both are currently default in selvbetjening)

    Example project 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 /fhir/DocumentReference/_search nhn:phr/mhd/read-documentreferences Find Document References (ITI-67)
GET /fhir/Document nhn:phr/mhd/read-document Retrieve Document (ITI-68)

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

Errors

The API returns errors as FHIR OperationOutcome resources.

Test data

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.

Table will be updated with test patiens in connected registry servers

Patient.identifier (NIN) Patient Name Example document Location
13116900216 LINE DANSER Brev - test CDA.pdf NHN document registry

more example data to come

Examples

Examples on how to use this API

Find Document References

Endpoint: HTTP POST /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.

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=13116900216&status=current

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

Retreive Document

Endpoint: HTTP POST /fhir/document

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

Query parameters:

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

Query parameter Description
patient Patient identifier (NIN)
documentUniqueId Global identifier for a document in Cross-enterprise document sharing for healthcare
homeCommunityId Identifier for participant's home community in Cross-enterprise document sharing for healthcare
repositoryUniqueId Unique ID for the document repository in Cross-enterprise document sharing for healthcare

Example GET request

GET api.pjd.test.nhn.no/fhir/document?patient=13116900216&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; 
Authorization: DPoP <DPoP authorization bearer token>
DPoP: <DPoP proof token>

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

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.