JFT ReadAPI overview

The ReadAPI provides endpoints for retrieving events and event status. As per FHIR conventions, the resource type is part of every endpoint address. The resource types currently supported are:

• Bundle
• Composition
• MedicationDispense

Available environments

Retrieving events

Event retrieval is supported by both GET and POST requests.

• GET is the primary and recommended approach.
• POST is supported on _search endpoints for clients that prefer sending parameters in the request body, which also avoids URL length limitations.
• Keyset pagination (also known as seek pagination) limits the number of events returned per request. This provides better performance for large datasets and prevents skipped or duplicate records when data changes during pagination.
• An opaque cursor parameter is used to retrieve the next page of results. The response Bundle includes a next link containing the cursor value.
• _lastUpdated limits results based on when events were last updated in JFT.
• _tag and _tag:not limit results based on whether journaling has been acknowledged for the event.

Endpoint format: GET /v1/<ResourceType> and POST /v1/<ResourceType>/_search

For example: GET /v1/Composition or POST /v1/Composition/_search retrieves events submitted as a FHIR Composition resource.

Metadata

When retrieving events, the API returns a FHIR Bundle containing the matching events. Each resource in the Bundle includes the following metadata:

• lastUpdated — The last time the event was updated in JFT.
• https://fhir.jft.nhn.no/parent-organization-number — The organization number of the municipality's main entity.
• https://fhir.jft.nhn.no/source-client-id — The HelseID client ID of the submitting client.
• https://fhir.jft.nhn.no/source-client-name — (Optional) The HelseID client name of the submitting client.
• https://fhir.jft.nhn.no/source-system-name — (Optional) The name of the submitting system. Can be set by the client by including the nhn-source-system header when submitting events.

{
  "meta": {
    "lastUpdated": "2026-05-26T10:06:17.01493+00:00",
    "tag": [
      {
        "system": "https://fhir.jft.nhn.no/parent-organization-number",
        "code": "313231593"
      },
      {
        "system": "https://fhir.jft.nhn.no/source-client-id",
        "code": "acdc0123-acdc-0123-4567-0123456789ab"
      },
      {
        "system": "https://fhir.jft.nhn.no/source-client-name",
        "code": "Bruno-Local"
      },
      {
        "system": "https://fhir.jft.nhn.no/source-system-name",
        "code": "Bruno V0.1.2"
      }
    ]
  }
}

Pagination example

To retrieve the first page with a limit of 10 items, include _count=10 in the query string (for GET) or request body (for POST).

Sorting order is controlled with the _sort parameter. The default is ascending by last updated time (_sort=_lastUpdated). To sort descending, use _sort=-_lastUpdated, following FHIR conventions.

Using GET:

GET /v1/Composition?_count=10&_sort=-_lastUpdated

Using POST:

POST /v1/Composition/_search
Content-Type: application/x-www-form-urlencoded

_count=10&_sort=-_lastUpdated

The response Bundle includes self and next link elements. The next link points to a GET endpoint and carries forward both the pagination cursor and the original query constraints:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://api.read.jft.test.nhn.no/v1/Composition?_count=10&_sort=-_lastUpdated"
    },
    {
      "relation": "next",
      "url": "https://api.read.jft.test.nhn.no/v1/Composition?cursor=ZXlKTVlYTjB..."
    }
  ]
}

To fetch the next page, follow the next link via GET. If you prefer POST, extract the opaque token from the cursor query parameter and include it in the request body:

POST /v1/Composition/_search
Content-Type: application/x-www-form-urlencoded

cursor=ZXlKTVlYTjB...

Cursor constraints:

• Treat the cursor value as completely opaque — do not attempt to decode or modify it.
• Combining search filters (_tag, _lastUpdated) with a cursor is not allowed and will result in a validation error.
• When a cursor is provided, the _sort parameter is ignored. Sort direction is fixed by the cursor and cannot be changed mid-pagination.

Retrieving event status

The status of a specific event is retrieved by making GET requests to the $status endpoints.

Endpoint format: GET /v1/<ResourceType>/<ResourceId>/$status

For example: GET /v1/Bundle/123/$status retrieves the status of an event submitted as a FHIR Bundle resource with resource ID 123 (resource IDs are GUIDs in practice).

A successful response is a simple JSON object (not a FHIR resource):

{
  "registered": "2025-02-14T12:01:02+00:00",
  "read": "2025-02-14T13:13:13+00:00",
  "journalingAcknowledged": "2025-02-14T13:13:15+00:00",
  "failed": null
}

The fields mean:

• registered — The time when the submitted event was processed by JFT.
• read — The time when the event was first retrieved (or null if unread).
• journalingAcknowledged — The time when a journaling acknowledgement was submitted for the event (or null if not acknowledged).
• failed — To be defined.

Required claim

The orgnr_parent claim is required in the access token for all endpoints. Its value must be the organization number of the municipality's main entity.