Import a CodeSystem

$import adds terminology concepts and their metadata to a CodeSystem. This operation changes server data; invoke it with POST. FHIR R4 does not define a standard CodeSystem/$import operation, so its availability and exact input constraints are implementation-specific.

Method	Path
POST	/fhir/R4/CodeSystem/$import

POST request

The import request is a FHIR Parameters resource. This example supplies a CodeSystem canonical URL, one concept, a property, and a German designation.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4/CodeSystem/$import' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/fhir+json' \
  --data @import-codesystem-parameters.json

Example import-codesystem-parameters.json:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "system",
      "valueUri": "https://example.org/fhir/CodeSystem/vitals"
    },
    {
      "name": "concept",
      "valueCoding": {
        "code": "HR",
        "display": "Heart rate"
      }
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "HR" },
        { "name": "property", "valueCode": "unit" },
        { "name": "value", "valueString": "bpm" }
      ]
    },
    {
      "name": "designation",
      "part": [
        { "name": "code", "valueCode": "HR" },
        { "name": "language", "valueCode": "de" },
        { "name": "value", "valueString": "Herzfrequenz" }
      ]
    }
  ]
}

• system identifies the CodeSystem by canonical URL. If using a CodeSystem-instance operation instead, the resource id identifies the target.
• Each concept parameter adds a code and optional display.
• Each property parameter associates metadata with a concept. Its parts identify the concept code, property name, and typed value.
• Each designation parameter adds an alternate display or translation. Its parts identify the concept code, optional language, and text value.

Successful response

The operation returns the CodeSystem resource that received the imported concepts. The exact response depends on existing CodeSystem content.

Response path	Example	Meaning
resourceType	CodeSystem	Identifies the returned FHIR resource.
url	https://example.org/fhir/CodeSystem/vitals	Canonical URL of the CodeSystem.
status	active	Status of the returned CodeSystem.
content	fragment	Indicates the resource contains a partial code system.
concept[].code, concept[].display	HR, Heart rate	Imported concept code and display.
concept[].property[]	unit = bpm	Additional typed metadata for the concept.
concept[].designation[]	language=de, value=Herzfrequenz	Alternate designation and language.

The returned CodeSystem is the updated resource; concept contains imported concepts and their properties/designations. Use the resource url or id to read it afterward.

The system, concept, property, and designation inputs follow the implementation-specific import operation documented by Medplum. Ovok deployments can differ; check the deployment's API reference if the request is rejected.

GET: read the CodeSystem after import

GET does not invoke $import. Use a regular CodeSystem search to inspect a resource after the write:

curl --get 'https://api.sandbox.ovok.com/fhir/R4/CodeSystem' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode 'url=https://example.org/fhir/CodeSystem/vitals'

This returns a FHIR searchset Bundle; its entry[].resource contains the matching CodeSystem. The CodeSystem/$import operation itself is POST-only because it changes server data.

Reference: Medplum CodeSystem $import.