CodeSystem $import

Large standard terminologies like SNOMED CT (350k+ codes) and LOINC (100k+ codes) are too large to manage within a single FHIR resource. The $import operation bulk-loads codes, display names, and metadata into a CodeSystem, enabling you to work with these essential terminologies efficiently.

Use Cases

• Loading standard terminologies: Import SNOMED CT, LOINC, RxNorm, or ICD code systems into your Medplum instance
• Custom code system management: Create and populate organization-specific code systems for internal coding standards
• Terminology updates: Incrementally add new codes or update metadata when new terminology versions are released
• Migration and synchronization: Import codes from existing terminology servers or legacy systems

[baseUrl]/CodeSystem/$import
[baseUrl]/CodeSystem/[id]/$import

Privileged Operation

This operation is only available to Project Admins and Super Admins.

Parameters

Name	Type	Description	Required
system	uri	The canonical URL of the code system to import into	No*
concept	Coding	A code, along with optional display text to add to the code system	No
property	Part[] (see below)	Metadata about codes in the code system to be imported	No
designation	Part[] (see below)	Additional synonyms or translations of codes' display text	No

note

^* If system is not provided, the operation must be invoked on a specific CodeSystem instance by ID.

Each property parameter contains a part array with three nested parameters:

Name	Type	Description	Required
code	code	The code to which the property applies	Yes
property	code	The property name (from CodeSystem.property.code)	Yes
value	string	The value of the property	Yes

Any designation parameters have three nested part parameters:

Name	Type	Description	Required
code	code	The code to which the synonym or translation applies	Yes
language	code	The language code for translations	No
value	string	Display string	Yes

Batch size

Each invocation of the $import operation can send a maximum of 1,000 of each parameter at a time, e.g. importing 1,000 concepts with one property and one designation each per request.

Output

The operation returns the CodeSystem resource representing the code system into which the given concepts and properties were imported.

Examples

Request:

const result = await medplum.post(medplum.fhirUrl('CodeSystem', '$import').toString(), {
  resourceType: 'Parameters',
  parameter: [
    { name: 'system', valueUri: 'http://example.com/local-codes' },
    { name: 'concept', valueCoding: { code: 'VS', display: 'Vital signs' } },
    { name: 'concept', valueCoding: { code: 'HR', display: 'Heart rate' } },
    {
      name: 'property',
      part: [
        { name: 'code', valueCode: 'VS' },
        { name: 'property', valueCode: 'child' },
        { name: 'value', valueString: 'HR' },
      ],
    },
    {
      name: 'property',
      part: [
        { name: 'code', valueCode: 'HR' },
        { name: 'property', valueCode: 'units' },
        { name: 'value', valueString: 'bpm' },
      ],
    },
  ],
});

Related

• CodeSystem $lookup - Look up code details after importing
• CodeSystem $validate-code - Validate codes within imported code systems
• ValueSet $expand - Expand value sets that reference imported code systems
• Medplum Terminology Guide - Overview of terminology services in Medplum
• FHIR CodeSystem Resource - FHIR specification for CodeSystem