CodeSystem $validate-code

Validating codes at the point of entry is necessary to prevent data quality issues that can cascade through analytics, clinical decision support, and interoperability workflows. Invalid codes can cause workflow failures, incorrect reports, and missed clinical alerts - all of which degrade clinical experiences.

The $validate-code operation checks whether a code exists within a specific code system and returns its display text if found. This is fundamental for data quality-ensuring that clinical data uses valid, recognized codes before storing or processing it.

Use Cases

• Form and Input Validation: Verify user-entered codes or confirm selected codes from autocomplete/typeahead are valid before saving clinical data
• Interface Validation: Check incoming codes from external systems (labs, pharmacies, EHRs) before processing
• Data Quality Checks: Audit existing data to identify invalid or deprecated codes
• Migration Validation: Ensure codes are valid when importing data from legacy systems

Invoke the $validate-code operation

[baseUrl]/CodeSystem/$validate-code
[baseUrl]/CodeSystem/[id]/$validate-code

Parameters

Name	Type	Description	Required
url	uri	The canonical URL of the CodeSystem to validate against	No*
version	string	The version of the code system to search.	No
code	string	The code to look up.	No†
coding	Coding	Look up via full Coding.	No†

^* If no url is provided, the operation must be invoked on a specific ValueSet instance.

^† One of code or coding must be provided.

Output

The operation returns a Parameters resource containing the validation result.

Name	Type	Description	Required
result	boolean	Whether or not the coding is from the given CodeSystem	Yes
display	string	The display text of the included code	No

Examples

Request:

curl 'https://api.medplum.com/fhir/R4/CodeSystem/$validate-code' \
  --get \
  -H "Authorization: Bearer $MY_ACCESS_TOKEN" \
  -d 'url=http://snomed.info/sct' \
  -d 'code=255604002'

Response: (200 OK)

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "result", "valueBoolean": true },
    { "name": "display", "valueString": "Mild (qualifier value)" }
  ]
}

Related

• ValueSet $validate-code - Validate codes against value sets
• CodeSystem $lookup - Get detailed information about a code
• CodeSystem $subsumes - Check hierarchical relationships
• Medplum Terminology Guide - Overview of terminology services
• FHIR CodeSystem $validate-code - FHIR specification