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.
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 inselvbetjening
)
Example project from HelseID for User Authentication with API access with DPoP apporach
- API-Access:
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
- FHIR server root is https://api.pjd.test.nhn.no
- Patient reference id is 13116900216 (LINE DANSER)
- status of current
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
nhn-source-system: EPJ System 1.0
nhn-event-id: <unique id>
Authorization: DPoP <DPoP authorization bearer token>
DPoP: <DPoP proof token>
patient.identifier=13116900216&status=current
Header Parameters
Header parameter | Required? | Possible values |
---|---|---|
nhn-access-basis | Only for Kjernejournalforskriften | UNNTAK, SAMTYKKE, FORHOYET_SAMTYKKE, AKUTT, FORHOYET_AKUTT |
Query Parameters
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 | |
---|---|---|---|
nhn-patient-nin | Header | Patient identifier (NIN), required to generate SAML assertion | |
nhn-source-system | Header | Required | Name and version of the EPJ system |
nhn-event-id | Header | Optional | Unique id from consumer |
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;
nhn-patient-nin: 13116900216
nhn-source-system: EPJ System 1.0
nhn-event-id: <unique id>
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.