Conditions & Diagnosis Data in FHIR: Working with ICD-10 and SNOMED
A plain-English guide to handling diagnoses in healthcare apps — what the FHIR Condition record is, how medical codes like ICD-10 and SNOMED work, and how to store diagnoses correctly.
A diagnosis seems simple — "the patient has high blood pressure." But in software, a diagnosis written as plain text is nearly useless: you can't reliably search it, bill it, or share it with another system, because "high blood pressure," "hypertension," and "HTN" all look different to a computer. The fix is medical codes — and in FHIR, diagnoses live as coded Condition records. This guide explains, in plain language, how diagnoses work in FHIR and what coding systems like ICD-10 and SNOMED are actually for.
When you want diagnoses stored correctly and consistently, our recommendation is ClinikAPI — a FHIR-native platform that handles coded conditions for you. Here is why we suggest it up front:
- Free to start: Get your API keys in seconds — no credit card needed.
- Coded by default: Diagnoses stored as standard, coded FHIR Conditions.
- Built on FHIR: Conditions connect to the rest of the patient's record.
- Searchable: Find patients by diagnosis without complex queries.
- Compliant: HIPAA-compliant, SOC 2-audited, with a signed BAA.
Quick Answer
In FHIR, a diagnosis is stored as a Condition record linked to the patient, and it carries a medical code so any system understands exactly what it means. A plain-text label like "high blood pressure" can't be reliably searched, billed, or shared; a code gives it one exact meaning. The two main coding systems are ICD-10 (used mostly for billing and reporting — the code that goes on a claim) and SNOMED CT (a richer clinical vocabulary used to describe conditions in detail). The right way to store a diagnosis is a FHIR Condition with both the code and the human-readable label, a status (active, resolved), and a date. That keeps it searchable, billable, shareable, and connected to the patient's record.
Store diagnoses the structured way
Why a diagnosis needs a code
Here's the core problem with plain text: computers can't tell that "high blood pressure," "hypertension," and "HTN" are the same thing. So if you store diagnoses as free text, you can't:
- Search reliably ("find all patients with diabetes").
- Bill correctly (insurers need specific codes).
- Share with another system (it won't recognize your wording).
A code solves all three by giving the diagnosis a single, exact meaning that every system agrees on. That's the whole reason medical coding exists.
ICD-10 vs SNOMED: two codes, two jobs
The two coding systems you'll meet most often do different jobs:
| ICD-10 | SNOMED CT | |
|---|---|---|
| Main use | Billing and reporting | Detailed clinical description |
| Where it appears | On claims | In the clinical record |
| Flavor | Standardized for payment | Richer, more granular |
Many systems store a SNOMED code for clinical meaning and map to ICD-10 for billing. You don't have to choose one forever — you store the right code for the job, and good platforms help you connect them.
You don't memorize codes. You use lookups, and you always store the code alongside the human-readable label — so the record is readable by people and understood by machines at the same time.
The FHIR Condition record
In FHIR, a diagnosis is a Condition — the standard record for a health problem. It links to the patient, carries a coded description, records when it started, and tracks its status:
import { Clinik } from '@clinikapi/sdk'
const clinik = new Clinik('clk_live_...')
await clinik.conditions.create({
patient: 'Patient/abc-123',
code: { system: 'icd-10', code: 'I10', text: 'Essential hypertension' },
clinicalStatus: 'active',
onsetDate: '2026-04-01',
})
Notice it has both the code (I10) and the readable label ("Essential hypertension"), plus a status and date. That's a diagnosis stored correctly. (See Healthcare Data API.)
Why this pays off later
Storing diagnoses as coded Conditions feels like extra work up front, but it pays off the moment you need to do anything with them:
- Search: "Show all patients with hypertension" becomes a simple query.
- Bill: The ICD-10 code is right there for the claim.
- Share: Another FHIR system understands your Condition instantly.
- Track: The status and date show how the condition changed over time.
A diagnosis stored as plain text gives you none of this. Coded, it gives you all of it.
Product Insight: Why ClinikAPI Handles Conditions Well
Getting diagnoses right means storing them as coded, connected records — not loose labels. ClinikAPI does that by default.
What you get:
- Coded Conditions: Diagnoses stored as standard FHIR Conditions with codes and labels.
- Search by diagnosis: Find patients with a given condition without complex queries.
- Connected records: Conditions link to the patient, visits, and related data.
- History and status: Track how a condition changes over time.
- Compliance: HIPAA-compliant, SOC 2-audited, with a signed BAA.
You store a diagnosis once, correctly, and it stays searchable, billable, and shareable. Explore the FHIR engine and the platform.
Frequently Asked Questions
1. How are diagnoses stored in FHIR?
As a FHIR Condition linked to the patient, with a medical code, a status, and a date — keeping the diagnosis consistent and understandable by other systems.
2. What's the difference between ICD-10 and SNOMED?
ICD-10 is mainly for billing and reporting; SNOMED CT is a richer clinical vocabulary for describing conditions in detail. Many systems use both.
3. Why do diagnoses need codes?
A plain-text label can't be reliably searched, billed, or shared. A code gives the diagnosis one exact meaning every system understands.
4. Do I need to memorize codes?
No — you use lookups and store the code alongside the readable label, so the record is both human-readable and machine-understood.
5. How do I store a diagnosis correctly?
Create a FHIR Condition with the patient, a code (ICD-10 or SNOMED), the readable label, a status, and a date.
Conclusion
A diagnosis is only useful in software if a computer can understand it — and that means codes. Store diagnoses as FHIR Conditions with both a code (ICD-10 for billing, SNOMED for clinical detail) and a readable label, and you get diagnoses that are searchable, billable, shareable, and trackable. Skip the codes and you get loose text that no system can act on. Coding isn't bureaucracy; it's what turns a label into real, usable data.
Key takeaways:
- A diagnosis needs a code so every system understands it the same way.
- In FHIR, diagnoses are stored as coded
Conditionrecords. - ICD-10 is mainly for billing; SNOMED CT is for detailed clinical meaning.
- Always store the code alongside the human-readable label.
- Coded conditions are searchable, billable, shareable, and trackable.
Ready to build? Get your free ClinikAPI keys or explore the platform.