Retrieve Inpatient and Outpatient Visits

A comprehensive view of a patient/member’s interactions with the healthcare system often requires gathering data from multiple claims and electronic medical record systems. This typically requires multiple FHIR resources including Claims (for paid claims), Encounters, and ServiceRequests (for authorizations). Furthermore, a variety of fields and value sets are often used to categorize visits and episodes of care based on healthcare setting such as inpatient, office vist, emergency, SNF, etc.

HIEBus provides a single $visits operation to gather a comprehensive view of a patient’s healthcare interactions and categorize by setting.

Retrieving Visits for a Patient/Member

The $visits operation can be called with a GET on the Patient resource. For example, GET https://[YOUR_FHIR_ENDPOINT]/Patient/aedf8090-8909-4a1e-9287-cda5e2525d63c/$visits?start=2012-01-01&end=2012-06-01&include-groups=true

The response will be in a Parameters resource with each parameter containing a single ‘visit’. Each visit has parts which include a name (encounter-visit, claim-visit, or service-request-visit) and a visit-type (and optionally a visit-subtype) containing healthcare setting (see below), and a visit-grouping.

Example response:

    "resourceType": "Parameters",
    "parameter": [
        {"name": "encounter-visit",
        "part": [
                {"name": "encounter",
                "resource": {
                        "resourceType": "Encounter",
                        "id": "...",
                {"name": "visit-type",
                "valueString": "Inpatient"},
                {"name": "visit-sub-type",
                "valueString": "HospitalEmergency"
        "name": "claim-visit",
        "part": [
                "name": "claim",
                "resource": {
                    "resourceType": "Claim",
                    "id": "...",
                {"name": "visit-type",
                "valueString": "Outpatient"}
        "name": "visit-grouping",
        "part": [
            {"name": "encounter-reference",
                "valueReference": {
                    "reference": "Encounter/..."}
            {"name": "claim-reference",
                "valueReference": {
                    "reference": "Claim/..."}
            {"name": "primary-visit",
                "valueReference": {
                    "reference": "Encounter/..."}

Categorizing Visits by Healthcare Setting

Potential types returned by the $visits operation include:

visit-type visit-sub-type (optional)
Inpatient HospitalInpatient
Outpatient Office

Since data varies greatly by source and even within a source, HIEBus uses business logic across multiple fields in Claims, Encounters, and ServiceRequests to assign visit-type and visit-sub-type.

Grouping Visits

HIEBus provides a data enhancement via the $visits operation which groups visits based on types and dates to approximate episodes of care such as an inpatient admission. Each visit-grouping in the response contains a list of references to resources contained above in the response and a primary-visit reference which may be used as the primary visit for display purposes.

Real-World Data Considerations

  • Diagnoses
    • Diagnoses can be found in:
      • Encounter.diagnosis as Reference(Condition).
      • Encounter.reasonCode as Reference(CodeableConcept) and/or Encounter.reasonReference as Reference(Condition) (not often populated).
      • Claim.diagnosis as Reference(CodeableConcept).
      • ServiceRequest.reasonCode as Reference(CodeableConcept) and/or ServiceRequest.reasonReference as Reference(Condition) (inconsistently populated).
    • If indicated in the source data the Claim.diagnosis.type may indicate if the diagnosis is ‘primary’. Encounter.diagnosis.rank is not typically populated, but Encounter.reasonCode or Encounter.reasonReference may indicate the primary diagnosis if present. If no diagnosis is indicated as ‘primary’, we recommend defaulting to the first diagnosis in the list and/or using value sets (e.g., CCSR or CCI) to identify ‘priority’ diagnoses for display, depending on the use case.
    • See Problem List for additional considerations.
  • Admissions and Discharges
    • Encounter.priority and ExplanationOfBenefit.supportingInfo.admtype may have admission type (e.g., emergency, elective) if available in source data.
    • If available, admission date may be found in Encounter.period.start or ExplanationOfBenefit.period.start and discharge data may be found in Encounter.period.end or ExplanationOfBenefit.period.end.
    • If a patient has an ED visit and is then admitted, this will typically result in a separate Encounter rather than the same Encounter with a change in type. However this depends on how the source data is received.
    • Location, including unit/room/bed if available, can be found in Encounter.location or Claim.facility as ReferenceLocation). Location.type may indicate facility, bed, etc. and may include the facility name or room number. However this is highly variable in source data.
    • Discharge disposition, if available, can be found in Encounter.hospitalization.dischargeDisposition. This is also highly variable in source data. The field will contain a mapping when available to the (UB04 discharge code system)[]{:target=”_blank” rel=”noopener”}
  • Providers
    • Providers can be found as Reference(Practitioner) in:
      • Claim.provider
      • Encounter.practitioner
      • ServiceRequest.performer
    • See Provider List for additional considerations.
  • Linking data
    • Infrequently, source data may contain links between Encounters, EOBs, and/or ServiceRequests.
    • If available, these links can be found in:
      • Claim.extension('')
      • Claim.preAuthRef
      • ServiceRequest.encounter
  • Future appointments
    • If available, future appointments can be found as Encounters with future dates.