Encounter

Encounter is a FHIR resource that records an interaction between a patient and healthcare providers for the purpose of providing healthcare services or assessing the health status of a patient.

Encounters document the administrative and clinical details of a patient visit, including the type of visit, location, participating providers, diagnoses addressed, and the time period of care. They serve as the connective tissue linking clinical activities to the context in which they occurred.

Encounter data is available from health insurers (derived from claims), medical record systems (from provider EHRs), and nationwide exchanges (via TEFCA). The level of detail varies by source — claims-derived encounters are typically summarized, while provider-sourced encounters may include richer clinical context.

Flexpa makes encounter data available as FHIR resources conforming to the US Core STU 6.1 Encounter Profile to support communicating USCDI v3 data. Data types used in this reference are defined in the FHIR R4 Data Types specification.

FHIR API

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

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

The FHIR R4 Encounter resource represents an interaction between a patient and healthcare provider(s). The US Core Encounter Profile constrains this resource to ensure consistent representation across US healthcare systems.

Encounters are structured around the visit context: who was seen, where and when the visit occurred, what type of visit it was, and why the patient was seen. They often reference other resources like Condition for diagnoses and Practitioner for participating providers.

Elements

metaMeta: Metadata about the resource. See also Tags defined by Flexpa.
lastUpdatedinstant: The last time the encounter was updated in the Endpoint's system of record
statuscode: The current status of the encounter; Codes
planned
The encounter is planned but has not yet started
arrived
The patient has arrived but the encounter has not yet begun
triaged
The patient has been triaged
in-progress
The encounter is currently in progress
onleave
The encounter has been paused (patient temporarily left)
finished
The encounter has ended normally
cancelled
The encounter was cancelled before it started
entered-in-error
The encounter was entered in error
unknown
The encounter status is not known
classCoding: Classification of patient encounter (e.g. ambulatory, emergency, inpatient); Systemhttp://terminology.hl7.org/CodeSystem/v3-ActCode
HL7 ActCode system for encounter classification
Codes
AMB
Ambulatory - a patient encounter where the patient is not admitted to the facility
EMER
Emergency - a patient encounter in an emergency department
FLD
Field - a patient encounter that takes place in a location other than a healthcare facility
HH
Home health - healthcare encounter at the patient's home
IMP
Inpatient encounter - a patient encounter where a patient is admitted to a facility
ACUTE
Inpatient acute - an acute inpatient encounter
NONAC
Inpatient non-acute - a non-acute inpatient encounter
OBSENC
Observation encounter - an encounter where the patient is under observation
PRENC
Pre-admission - a patient encounter before admission to a facility
SS
Short stay - a patient encounter in a short stay facility
VR
Virtual - a patient encounter via telehealth or other virtual means
typeCodeableConcept[]: Specific type of encounter (e.g. office visit, home health visit). Bound to the US Core Encounter Type value set (extensible).; Systemhttp://www.ama-assn.org/go/cpt
CPT codes are commonly used as encounter type codes
Example Codes
99213
Office or other outpatient visit, established patient, low complexity
99214
Office or other outpatient visit, established patient, moderate complexity; Systemhttp://snomed.info/sct
SNOMED CT codes for encounter types
Example Codes
185349003
Encounter for check up
308335008
Patient encounter procedure
subjectReference(Patient): Reference to the Patient present at the encounter
participantBackboneElement[]: Providers involved in the encounter
typeCodeableConcept[]: Role of participant in the encounter; Systemhttp://terminology.hl7.org/CodeSystem/v3-ParticipationType
HL7 participation type codes
Codes
ATND
Attender - the practitioner that has responsibility for overseeing a patient's care
ADM
Admitter - the practitioner who is responsible for admitting a patient
DIS
Discharger - the practitioner who is responsible for the discharge of a patient
CON
Consultant - an advisor participating in the encounter by providing guidance
REF
Referrer - the practitioner that referred the patient
periodPeriod: Period of time during the encounter that the participant was present
individualReference(Practitioner|PractitionerRole): Reference to the individual provider involved
periodPeriod: The start and end time of the encounter
startdateTime: Starting time with inclusive boundary
enddateTime: End time with inclusive boundary, if the encounter has ended
reasonCodeCodeableConcept[]: Coded reason the encounter takes place; Systemhttp://snomed.info/sct
SNOMED CT codes for encounter reasons
Example Codes
185349003
Encounter for check up; Systemhttp://hl7.org/fhir/sid/icd-10-cm
ICD-10-CM codes used as encounter reasons
Example Codes
Z00.00
Encounter for general adult medical examination without abnormal findings
reasonReferenceReference(Condition|Procedure|Observation)[]: Reference to reason the encounter takes place, such as a Condition, Procedure, or Observation
diagnosisBackboneElement[]: The list of diagnoses relevant to this encounter
conditionReference(Condition): Reference to the Condition diagnosed during this encounter
useCodeableConcept: Role that this diagnosis has within the encounter (e.g. admission, billing, discharge); Systemhttp://terminology.hl7.org/CodeSystem/diagnosis-role
Diagnosis role codes
Codes
AD
Admission diagnosis
DD
Discharge diagnosis
CC
Chief complaint
CM
Comorbidity diagnosis
pre-op
Pre-op diagnosis
post-op
Post-op diagnosis
billing
Billing diagnosis
rankpositiveInt: Ranking of the diagnosis (for each role type)
hospitalizationBackboneElement: Details about the admission to a healthcare service, primarily for inpatient encounters
dischargeDispositionCodeableConcept: Category or kind of location after discharge; Systemhttp://terminology.hl7.org/CodeSystem/discharge-disposition
Discharge disposition codes
Example Codes
home
Discharged to home
snf
Discharged to skilled nursing facility
rehab
Discharged to rehabilitation facility; Systemhttps://www.nubc.org/CodeSystem/PatDischargeStatus
NUBC Patient Discharge Status codes from the UB-04
Example Codes
01
Discharged to home or self care (routine discharge)
03
Discharged/transferred to skilled nursing facility
locationBackboneElement[]: List of locations where the patient has been during this encounter
locationReference(Location): Reference to the Location where the encounter took place
serviceProviderReference(Organization): The organization that is primarily responsible for this encounter's services - see also the EndpointId tag provided by Flexpa

Encounter Example

{
  "resourceType": "Encounter",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "meta": {
    "lastUpdated": "2024-03-15T10:30:00Z",
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter"
    ]
  },
  "status": "finished",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  },
  "type": [
    {
      "coding": [
        {
          "system": "http://www.ama-assn.org/go/cpt",
          "code": "99213",
          "display": "Office or other outpatient visit, established patient"
        }
      ]
    }
  ],
  "subject": {
    "reference": "Patient/example"
  },
  "participant": [
    {
      "type": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
              "code": "ATND",
              "display": "attender"
            }
          ]
        }
      ],
      "period": {
        "start": "2024-03-15T09:00:00Z",
        "end": "2024-03-15T09:30:00Z"
      },
      "individual": {
        "reference": "Practitioner/example",
        "display": "Dr. Jane Smith, MD"
      }
    }
  ],
  "period": {
    "start": "2024-03-15T09:00:00Z",
    "end": "2024-03-15T09:30:00Z"
  },
  "reasonCode": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/sid/icd-10-cm",
          "code": "Z00.00",
          "display": "Encounter for general adult medical examination without abnormal findings"
        }
      ]
    }
  ],
  "diagnosis": [
    {
      "condition": {
        "reference": "Condition/example"
      },
      "use": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/diagnosis-role",
            "code": "billing"
          }
        ]
      }
    }
  ],
  "location": [
    {
      "location": {
        "reference": "Location/example",
        "display": "Primary Care Clinic"
      }
    }
  ],
  "serviceProvider": {
    "reference": "Organization/example",
    "display": "Example Health System"
  }
}

#Example FHIRPaths

Data Point	FHIRPath Expression
Encounter class	`class.code`
Encounter type codes	`type.coding`
Encounter start date	`period.start`
Encounter period (with fallback)	`(period.start \| period.end).first()`
Attending provider	`participant.where(type.coding.code = 'ATND').individual`
Diagnosis conditions	`diagnosis.condition`
Discharge disposition	`hospitalization.dischargeDisposition.coding`
Service provider	`serviceProvider`

#API

GEThttps://api.flexpa.com/fhir/Encounter/: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 be sent with a Patient Access Token or an Application Access Token

Request path parameters

idstring: The id 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/Encounter/:id

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/Encounter/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

#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 be sent with a Patient Access Token or an Application Access Token

Search parameters

_idtoken: The logical ID of the resource
patientreference: The patient or group present at the encounter
datedate: A date within the period the encounter lasted
classtoken: Classification of the encounter (e.g. AMB, IMP, EMER)
typetoken: Specific type of encounter
statustoken: Current status of the encounter
identifiertoken: Identifier(s) by which this encounter is known
diagnosisreference: The diagnosis or procedure relevant to the encounter
locationreference: Location the encounter takes place
participantreference: Persons involved in the encounter other than the patient
participant-typetoken: Role of participant in the encounter
service-providerreference: The organization (facility) responsible for this encounter
reason-codetoken: Coded reason the encounter takes place
reason-referencereference: Reason the encounter takes place (reference)

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/Encounter

ACCESS_TOKEN=flexpa-link-access-token

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

FHIR API

New to FHIR?

Intro to FHIR

Related

Claims to Clinical

Elements

Encounter Example

Request headers

Request path parameters

Error codes

Request

Request headers

Search parameters

Error codes

Request