Termbox Docs

FHIR API

Termbox supports all R4, R5, and R6 normative operations on ValueSets and CodeSystems[^4]

Support Legend

  • ✅ Full support - Complete implementation with all parameters
  • 🏗️ In development - Under development, expect partial support in the meantime
  • ❌ No support - In our roadmap
  • 🚫 Won't support - Not in our roadmap

Operations

OperationDescriptionSupport
CodeSystem/$lookupGiven a code/system, get additional details about the concept. See docs✅
CodeSystem/$validate-codeValidates a coded value. See docs✅
CodeSystem/$subsumesTest the subsumption relationship between A and B. See docs✅
CodeSystem/$find-matchesGiven a set of properties (and text), return one or more possible matching codes. See docs. Supported via $x-multi-invoke.✅
ValueSet/$expandReturns an expansion of concepts according to the value set definition. See docs✅
ValueSet/$validate-codeValidate that a coded value is in the set of codes allowed by a value set. See docs✅
ConceptMap/$translateTranslate a code from one terminology to another. See docs✅
ConceptMap/$closureMaintenance of a client-side transitive closure table. See docs❌
/$x-multi-invokeTermbox extension: invoke a supported operation over multiple entries in a single request. See $x-multi-invoke.✅

Features

FeatureDescriptionSupport
Capability Statements+ TerminologyCapabilities✅
CRUD of Terminology resourcesCreate, Read, Update, Delete operations🏗️
Pre-coordinated codesStandard coded concepts✅
Post-coordinated codesComplex expressions not yet supported❌
Intensional ValueSetsFilter-based ValueSet definitions✅
Extensional ValueSetsExplicit concept enumeration✅
ValueSet expansionFull expansion with pagination✅
ValueSet validationCode membership validation✅
ValueSet inclusion/exclusionDeep set operations support✅
Lookup displays, designation, and propertiesAll concept attributes✅
Full text search filterPrefix, stemming, phrase matching✅
FTS rankingFull text search ranking based on relevance✅
Property filtersProperty-based filtering: =, in, regex, etc✅
Subsumption filteringis-a, generalizes, ancestors, etc✅
Active/Inactive filteringVia status, inactive, notSelectable, etc✅
Multi-language supportTranslations via displaylanguage, HTTP header, designation, etc✅
Hierarchy via propertiese.g.: parent, child, PAR, CHD, etc✅
Nested conceptsHierarchy via concept.concept✅
Supplemental CodeSystemsAdditional concept properties and designations🏗️
Implicit ValueSetsSystem-generated ValueSets✅
ConceptMap translationsCode mapping between terminology systems✅
Multiple ConceptMap matchesReturns all applicable mappings for source code✅
Transitive closure table$closure❌
Syntax-based code systemsUCUM, BCP-47, HGVS, etc❌
tx-resource parameterInline resource definitions✅
Ad-hoc ValueSetsValueSet as a Parameter✅
R4/R5/R6 format conversionOne server, one database, multiple FHIR versions❌
Batch validationValidation of many codes in one request🏗️

Extension Operations

$x-multi-invoke

POST /fhir/$x-multi-invoke

Invokes a FHIR operation over multiple entries in a single request. This operation allows for high-throughput batch invocation of supported operations.

Supported operations

operation valueDescription
CodeSystem/$find-matchesMatch each entry's display text against concepts in a CodeSystem.

Request parameters

The request body is a FHIR Parameters resource with the following parameters:

NameTypeDescription
operationuriThe operation to invoke, e.g. CodeSystem/$find-matches.
sharedpartParameters shared across all entries. Parts: system (uri, required), version (string, optional).
entrypart[]One entry per lookup. Parts: display (string, required), system (uri, optional), version (string, optional). Entry-level system / version overrides the shared values.

Response

Returns a Parameters resource with one entry per input entry (in the same order). Each entry.part contains zero or more match elements. An entry with no matching concept returns an empty part array.

Example

POST /fhir/$x-multi-invoke
Content-Type: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "operation", "valueUri": "CodeSystem/$find-matches" },
    {
      "name": "shared",
      "part": [
        { "name": "system",  "valueUri": "http://snomed.info/sct" },
        { "name": "version", "valueString": "http://snomed.info/sct/83821000000107/version/20260211" }
      ]
    },
    { "name": "entry", "part": [{ "name": "display", "valueString": "Acute appendicitis" }] },
    { "name": "entry", "part": [{ "name": "display", "valueString": "Type 2 diabetes mellitus" }] },
    { "name": "entry", "part": [{ "name": "display", "valueString": "this description does not exist" }] }
  ]
}

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "entry",
      "part": [
        { "name": "match", "part": [{ "name": "code", "valueCode": "85189001" }] }
      ]
    },
    {
      "name": "entry",
      "part": [
        { "name": "match", "part": [{ "name": "code", "valueCode": "44054006" }] }
      ]
    },
    {
      "name": "entry",
      "part": []
    }
  ]
}

Matching is exact and case-sensitive. Per-entry system and version parts can be used to look up across different code systems in a single request.

FHIR Versions

Termbox runs one endpoint for each major FHIR version[^5] and a default endpoint (currently R5, users will be able to configure this in upcoming releases)

  • Default: /fhir/
  • Version specific: /fhir/:version/

Examples:

  • R6: GET /fhir/r6/ValueSet/$expand
  • R4B: GET /fhir/r4b/metadata

Last updated: