Treatment groups

v1 (/api/v1/*) is authenticated with the X-API-KEY header; v2 (/api/v2/*) with a HelseID access token (DPoP). See Authentication. Shared topics: response format, status codes and rate limiting.

GET /api/v1/treatment-group

Returns treatment group data. Supports filtering and version-based diff queries.

Parameters

Response

Default (no since-version, no versioned=true) — unversioned shape:

{
  "entries": [
    {
      "treatmentGroup": { ... }
    }
  ]
}

With versioned=true or since-version — versioned shape:

{
  "currentVersion": 5,
  "entries": [
    {
      "treatmentGroup": { ... },
      "version": 5,
      "lastChanged": "2025-04-10T08:30:00Z",
      "isDeleted": false
    }
  ]
}

Without since-version: Returns all non-deleted items. isDeleted is always false (only present when the versioned shape is used).

With since-version: Always returns the versioned shape, with items with version > N, including deleted items. isDeleted may be true either because the item was removed from the source system or because all of its products lost their FEST match and the item is no longer visible in a default full response. A later FEST match can return the item again with isDeleted: false.

Example

# Get all (unversioned, default)
curl -H "X-API-KEY: key" \
  https://api.example.com/api/v1/treatment-group

# Get all (versioned envelope)
curl -H "X-API-KEY: key" \
  "https://api.example.com/api/v1/treatment-group?versioned=true"

# Get changes since version 3 (always versioned)
curl -H "X-API-KEY: key" \
  https://api.example.com/api/v1/treatment-group?since-version=3

# Filter on indication code
curl -H "X-API-KEY: key" \
  https://api.example.com/api/v1/treatment-group?indication=G35

GET /api/v1/treatment-group/

Returns a treatment group.

Parameters

Response

Default (no versioned=true) — unversioned shape (shown below without the version/ lastChanged/isDeleted fields present only in the versioned shape):

{
  "treatmentGroup": {
    "id": "...",
    "name": "...",
    "description": "...",
    "diseaseGroup": "...",
    "jurisdictions": [
      {
        "system": "...",
        "code": "100022",
        "display": "Helse Nord RHF"
      }
    ],
    "validityPeriod": {
      "start": "...",
      "end": "..."
    },
    "reviewDate": "...",
    "indications": [
      {
        "coding": [
          {
            "system": "...",
            "code": "C500",
            "display": "..."
          }
        ],
        "text": null
      }
    ],
    "treatmentAlternatives": [
      {
        "rank": 1,
        "treatmentId": "...",
        "name": "Atezolizumab (Tecentriq)",
        "description": "...",
        "products": [
          {
            "identifiers": [
              {
                "type": "FEST/LegemiddelPakning/Varenummer",
                "value": "448992",
                "display": "Atezolizumab 420 mg/14 ml koncentration til injeksjonsvæske, injeksjon"
              },
              {
                "type": "FEST/LegemiddelPakning/Id",
                "value": "3F2504E0-4F89-11D3-9A0C-0305E82C3301",
                "display": "Atezolizumab 420 mg/14 ml koncentration til injeksjonsvæske, injeksjon"
              },
              {
                "type": "FEST/LegemiddelMerkevare/Id",
                "value": "7C9E6679-7425-40DE-944B-E07FC1F90AE7",
                "display": "Atezolizumab 420 mg/14 ml koncentration til injeksjonsvæske, injeksjon"
              },
              {
                "type": "FEST/LegemiddelVirkestoff/Id",
                "value": "E4EAAAF2-D142-11E1-B3E4-080027620CDD",
                "display": "Atezolizumab"
              }
            ]
          }
        ]
      }
    ]
  }
}

With versioned=true — adds the version metadata around the same treatmentGroup object:

{
  "treatmentGroup": { ... },
  "version": 1,
  "lastChanged": "2026-06-23T09:17:13.113Z",
  "isDeleted": false
}

Explanation of content of indetifiers:

The Varenummer of a product may be an article number that FEST has marked as expiring or expired. Such a number still resolves to the FEST identifiers (LegemiddelPakning/Id, LegemiddelMerkevare/Id, LegemiddelVirkestoff/Id) of the package it belongs to, as long as that package is active in FEST. The product's own Varenummer is returned as supplied by the source and is not replaced by the package's current article number.

Each identifier carries an optional display with the human-readable name of the referenced FEST entry: the package name (NavnFormStyrke) for the Varenummer and LegemiddelPakning/Id entries, the brand name (NavnFormStyrke) for LegemiddelMerkevare/Id, and the plain substance name (Virkestoff.Navn) for LegemiddelVirkestoff/Id. display is omitted when FEST has no name for the entry (e.g. the Missing sentinel, or substances referenced without a strength value).

FEST supplies its own internal ids (LegemiddelPakning/Id, LegemiddelMerkevare/Id, LegemiddelVirkestoff/Id) as a string with an ID_ prefix, e.g. ID_3F2504E0-4F89-11D3-9A0C-0305E82C3301. This API stores those ids internally as Guid and returns them in value as the bare uppercase Guid without the ID_ prefix (e.g. 3F2504E0-4F89-11D3-9A0C-0305E82C3301). The Varenummer identifier is unaffected — it is a plain article number, not a FEST ID_-prefixed id.

HelseID (v2) endpoints

The v2 endpoints return the same data as their v1 counterparts, authenticated with HelseID.

GET /api/v2/treatment-group

Returns treatment group data. Supports the same filtering and version-based diff queries as GET /api/v1/treatment-group.

Parameters

Identical to GET /api/v1/treatment-group (since-version, versioned, name, disease-group, jurisdiction, indication, vare-nr, effective-date, ignore-fest-validation).

Response

Same envelope and entry shape as GET /api/v1/treatment-group.

Example

# Get all (authenticated with a HelseID DPoP access token + proof)
curl -H "Authorization: DPoP <access-token>" \
     -H "DPoP: <proof-jwt>" \
     https://api.example.com/api/v2/treatment-group

# Get changes since version 3
curl -H "Authorization: DPoP <access-token>" \
     -H "DPoP: <proof-jwt>" \
     https://api.example.com/api/v2/treatment-group?since-version=3

GET /api/v2/treatment-group/

Returns a single treatment group. Same id parameter and response shape as GET /api/v1/treatment-group/{id}.

Schema

Field types marked as links are described in Shared types.

TreatmentGroup

Represents a treatment group with ranked treatment alternatives for a specific disease.

{
  "id": "string",
  "name": "string",
  "description": "string | null",
  "diseaseGroup": "string | null",
  "jurisdictions": [ Coding ],
  "validityPeriod": { "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" },
  "reviewDate": "YYYY-MM-DD | null",
  "indications": [ CodeableConcept ],
  "treatmentAlternatives": [ TreatmentAlternative ]
}

TreatmentAlternative

A specific treatment option within a treatment group, ranked by preference.

{
  "rank": 1,
  "treatmentId": "string",
  "name": "string",
  "description": "string | null",
  "products": [ ProductReference ]
}