Condition

Condition is a FHIR resource that records detailed information about a condition, problem, diagnosis, or other clinical concept that has risen to a level of concern. Conditions represent a patient's active problems, resolved diagnoses, and health concerns.

Condition resources are a primary source of diagnostic information, documenting what conditions a patient has or has had using standard coding systems like ICD-10-CM, ICD-9-CM, and SNOMED CT. They are essential for understanding a patient's problem list, tracking chronic conditions, identifying gaps in care, and supporting risk adjustment and quality measurement workflows.

US Core STU 6.1 defines two additional FHIR profiles for Condition to support communicating USCDI v3 data:

Encounter Diagnosis - Conditions diagnosed during a specific encounter, typically derived from claims data
Problems and Health Concerns - Long-term conditions on a patient's problem list or health concerns being tracked over time

Flexpa makes condition data available as FHIR resources conforming to the Encounter Diagnosis and Problems and Health Concerns profiles. Data types used in this reference are defined in the FHIR R4 Data Types specification.

FHIR API

https://api.flexpa.com/fhir/Condition

New to FHIR?

Intro to FHIR

FHIR, or Fast Healthcare Interoperability Resources, is a standard for exchanging healthcare information electronically

Read introduction →

Claims to Clinical

Flexpa generates US Core Encounter, Condition, and Procedure resources from ExplanationOfBenefit claims data

View Claims to Clinical →

#Schema

#All Conditions

The FHIR R4 Condition resource represents a clinical condition, problem, diagnosis, or other event. Both US Core Condition profiles share a common set of elements documented below.

All Conditions, regardless of profile, share elements that describe what the condition is, who has it, and its current clinical and verification status. The category element distinguishes between the two profiles: problem-list-item or health-concern for the Problems and Health Concerns profile, and encounter-diagnosis for the Encounter Diagnosis profile.

Elements

metaMeta: Metadata about the resource. See also Tags defined by Flexpa.
lastUpdatedinstant: The last time the condition was updated in the Endpoint's system of record
clinicalStatusCodeableConcept: The clinical status of the condition; Systemhttp://terminology.hl7.org/CodeSystem/condition-clinical
HL7 Condition Clinical Status codes
Codes
active
The subject is currently experiencing the condition or there is evidence of the condition
recurrence
The subject is experiencing a re-occurrence or repeating of a previously resolved condition
relapse
The subject is experiencing a return of a condition after a period of improvement
inactive
The subject is no longer experiencing the condition or there is no longer evidence of the condition
remission
The subject is no longer experiencing the condition, but there is a risk of the condition recurring
resolved
The subject is no longer experiencing the condition and there is no evidence of recurrence
verificationStatusCodeableConcept: The verification status to support the clinical status of the condition; Systemhttp://terminology.hl7.org/CodeSystem/condition-ver-status
HL7 Condition Verification Status codes
Codes
unconfirmed
There is not sufficient evidence to assert the presence of the condition
provisional
This is a tentative diagnosis - still a candidate that is under consideration
differential
One of a set of potential (and typically mutually exclusive) diagnoses asserted to further guide the diagnostic process
confirmed
There is sufficient evidence to assert the presence of the condition
refuted
This condition has been ruled out by subsequent diagnostic and clinical evidence
entered-in-error
The statement was entered in error and is not valid
codeCodeableConcept: Identification of the condition, problem, or diagnosis. Bound to the US Core Condition Codes value set (extensible).; Systemhttp://hl7.org/fhir/sid/icd-10-cm
ICD-10-CM (International Classification of Diseases, 10th Revision, Clinical Modification) - the primary diagnosis coding system in US healthcare
Example Codes
E11.9
Type 2 diabetes mellitus without complications
I10
Essential (primary) hypertension
J06.9
Acute upper respiratory infection, unspecified; Systemhttp://snomed.info/sct
SNOMED CT clinical terminology codes for conditions
Example Codes
44054006
Type 2 diabetes mellitus
38341003
Hypertensive disorder; Systemhttp://hl7.org/fhir/sid/icd-9-cm
ICD-9-CM (International Classification of Diseases, 9th Revision, Clinical Modification) - legacy diagnosis coding system still present in historical data
Example Codes
250.00
Diabetes mellitus without mention of complication, type II
401.9
Unspecified essential hypertension
subjectReference(Patient): Reference to the Patient who has the condition
onsetDateTimedateTime: Estimated or actual date the condition began, as a single date
onsetPeriodPeriod: Estimated or actual date range the condition began
abatementDateTimedateTime: When the condition resolved or went into remission
recordedDatedateTime: Date the condition was first recorded
extension:assertedDatedateTime: The assertedDate extension records the date the condition was first asserted

All Conditions Example

{
  "resourceType": "Condition",
  "id": "d562ef6d-8e08-40b3-a48c-614c2154a876",
  "meta": {
    "lastUpdated": "2024-03-15T10:30:00Z"
  },
  "identifier": [
    {
      "system": "https://example-payer.com/fhir/condition-ids",
      "value": "cond-diabetes-001"
    }
  ],
  "clinicalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
        "code": "active"
      }
    ]
  },
  "verificationStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
        "code": "confirmed"
      }
    ]
  },
  "code": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "code": "E11.9",
        "display": "Type 2 diabetes mellitus without complications"
      }
    ],
    "text": "Type 2 diabetes mellitus"
  },
  "subject": {
    "reference": "Patient/example"
  },
  "onsetDateTime": "2020-06-15",
  "recordedDate": "2020-06-15"
}

#Encounter Diagnosis

The US Core Condition Encounter Diagnosis Profile represents diagnoses made during a specific encounter. These are typically point-in-time diagnoses that are directly associated with a visit and are commonly derived from claims data.

Encounter diagnoses represent what was diagnosed or treated during a specific visit rather than a long-term problem list. They are available from health insurers (mapped from claims data), medical record systems (from provider EHRs), and nationwide exchanges (via TEFCA).

This profile constrains the base Condition resource by requiring category to be encounter-diagnosis, making encounter a must-support reference, and adding the assertedDate extension.

Elements

categoryCodeableConcept[]: Constrained to encounter-diagnosis; Systemhttp://terminology.hl7.org/CodeSystem/condition-category
Standard condition categories
Codes
encounter-diagnosis
A point-in-time diagnosis related to an encounter
encounterReference(Encounter): Reference to the Encounter during which this diagnosis was made

Encounter Diagnosis Example

{
  "resourceType": "Condition",
  "id": "encounter-diagnosis-example",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-condition-encounter-diagnosis"
    ]
  },
  "clinicalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
        "code": "active"
      }
    ]
  },
  "verificationStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
        "code": "confirmed"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/condition-category",
          "code": "encounter-diagnosis",
          "display": "Encounter Diagnosis"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "code": "J06.9",
        "display": "Acute upper respiratory infection, unspecified"
      }
    ],
    "text": "Upper respiratory infection"
  },
  "subject": {
    "reference": "Patient/example"
  },
  "encounter": {
    "reference": "Encounter/example"
  },
  "recordedDate": "2024-03-15"
}

#Example FHIRPaths

Data Point	FHIRPath Expression
Encounter diagnoses	`category.coding.where(code = 'encounter-diagnosis')`
All diagnosis codes	`code.coding`
ICD-10-CM codes	`code.coding.where(system = 'http://hl7.org/fhir/sid/icd-10-cm')`
ICD-9-CM codes	`code.coding.where(system = 'http://hl7.org/fhir/sid/icd-9-cm')`
Associated encounter	`encounter`
Condition date (with fallback)	`(recordedDate \| onsetDateTime).first()`

#Problems and Health Concerns

The US Core Condition Problems and Health Concerns Profile represents conditions that are tracked on a patient's problem list or health concerns being monitored over time. These are long-lived records that reflect the patient's ongoing health status.

Problem list items are typically managed by providers and represent active, chronic, or historically significant diagnoses. Health concerns may include broader issues like social determinants of health or wellness goals. In payer data, problem list conditions are often derived from clinical data exchange with providers.

Conditions using this profile will have category set to problem-list-item or health-concern.

Elements

categoryCodeableConcept[]: Constrained to problem-list-item or health-concern; Systemhttp://terminology.hl7.org/CodeSystem/condition-category
Condition category codes
Codes
problem-list-item
An item on a patient's problem list that is managed over time
health-concern
A health concern tracked by a provider; Systemhttp://hl7.org/fhir/us/core/CodeSystem/us-core-category
USCDI Health Status/Assessments Data Class
Codes
sdoh
Social Determinants of Health category
functional-status
Functional Status category
disability-status
Disability Status category
cognitive-status
Cognitive Status category

Problems and Health Concerns Example

{
  "resourceType": "Condition",
  "id": "problem-list-example",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-condition-problems-health-concerns"
    ]
  },
  "clinicalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
        "code": "active"
      }
    ]
  },
  "verificationStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
        "code": "confirmed"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/condition-category",
          "code": "health-concern",
          "display": "Health Concern"
        }
      ]
    },
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-category",
          "code": "sdoh",
          "display": "SDOH"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "code": "I10",
        "display": "Essential (primary) hypertension"
      },
      {
        "system": "http://snomed.info/sct",
        "code": "38341003",
        "display": "Hypertensive disorder"
      }
    ],
    "text": "Hypertension"
  },
  "subject": {
    "reference": "Patient/example"
  },
  "onsetDateTime": "2019-03-10",
  "recordedDate": "2019-03-10"
}

#Example FHIRPaths

Data Point	FHIRPath Expression
Problem list items	`category.coding.where(code = 'problem-list-item')`
Health concerns	`category.coding.where(code = 'health-concern')`
Active conditions	`clinicalStatus.coding.where(code = 'active')`
ICD-10-CM codes	`code.coding.where(system = 'http://hl7.org/fhir/sid/icd-10-cm')`
SNOMED CT codes	`code.coding.where(system = 'http://snomed.info/sct')`
Onset date (with fallback)	`(onsetDateTime \| onsetPeriod.start \| recordedDate).first()`

#API

GEThttps://api.flexpa.com/fhir/Condition/:id

#Read

A read is the most basic operation in FHIR. It allows you to retrieve the current version of a single resource by its ID.

For a full list of available Resources, please refer to the FHIR Resources documentation.

Request headers

AuthorizationstringRequired: An Authorization: Bearer header value must presented with a Patient Access Token or an Application Access Token

Request path parameters

identifierstring: The identifier of the resource to be retrieved - used in the last part of the URL path segment

Error codes

transient429 status code: The API is expected to return a 429 status code until the data is ready to be retrieved. This error is returned by the API while in the initial sync period, which typically lasts less than 1 minute.; You will need to implement retry logic to handle this error. If you are using the Node SDK which we demonstrate in our Quickstart guide, retry logic is already built in and you don't need to implement it yourself.
processing422 status code: The API is expected to return a 422 when Flexpa fails to synchronize any resources from the Endpoint for the requested Patient. Please re-authorize or reach out to support.

Request

GET

/fhir/Condition/:id

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/Condition/d562ef6d-8e08-40b3-a48c-614c2154a876 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GEThttps://api.flexpa.com/fhir/Condition

#Search

Searches on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource with parameters to define the exact search criteria to filter the response.

Request headers

AuthorizationstringRequired: An Authorization: Bearer header value must presented with a Patient Access Token or an Application Access Token

Search parameters

_idtoken: The logical ID of the resource
patientreference: Who has the condition
categorytoken: The category of the condition (problem-list-item, encounter-diagnosis, health-concern)
clinical-statustoken: The clinical status of the condition (active, recurrence, relapse, inactive, remission, resolved)
codetoken: Code for the condition
onset-datedate: Date related onsets (dateTime and Period)
recorded-datedate: Date record was first recorded
verification-statustoken: The verification status of the condition
identifiertoken: A unique identifier of the condition
encounterreference: Encounter when condition first asserted

Error codes

transient429 status code: The API is expected to return a 429 status code until the data is ready to be retrieved. This error is returned by the API while in the initial sync period, which typically lasts less than 1 minute.; You will need to implement retry logic to handle this error. If you are using the Node SDK which we demonstrate in our Quickstart guide, retry logic is already built in and you don't need to implement it yourself.
processing422 status code: The API is expected to return a 422 when Flexpa fails to synchronize any resources from the Endpoint for the requested Patient. Please re-authorize or reach out to support.

Request

GET

/fhir/Condition

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/Condition \
  -H "Authorization: Bearer $ACCESS_TOKEN"

FHIR API

New to FHIR?

Intro to FHIR

Related

Claims to Clinical

Elements

All Conditions Example

Elements

Encounter Diagnosis Example

Elements

Problems and Health Concerns Example

Request headers

Request path parameters

Error codes

Request

Request headers

Search parameters

Error codes

Request