Encounter

Overview

The Encounter resource represents interactions between patients and healthcare providers for delivering services or assessing health status. This resource is fundamental to clinical workflows and serves as the context for many other clinical resources.

Important: Always validate Encounter resource support and available operations by retrieving the current CapabilityStatement from /metadata before implementing integrations.

Resource Schema

The Encounter resource follows the HL7 FHIR R4 Encounter specification with Netsmart-specific extensions.

Key elements include:

• identifier - Unique encounter identifiers
• status - Planned, arrived, triaged, in-progress, onleave, finished, cancelled
• statusHistory - List of past encounter statuses
• class - Classification of encounter (inpatient, outpatient, emergency)
• type - Specific type of encounter
• serviceType - Broad categorization of service
• priority - Urgency of encounter
• subject - Patient present at encounter
• episodeOfCare - Episode(s) of care this encounter belongs to
• basedOn - Service request that initiated encounter
• participant - List of people involved in encounter
• appointment - Appointment that scheduled encounter
• period - Start and end time of encounter
• length - Duration of encounter
• reasonCode - Coded reason for encounter
• diagnosis - List of diagnoses relevant to encounter
• account - Account associated with encounter
• hospitalization - Details about admission/discharge
• location - List of locations where encounter takes place
• serviceProvider - Organization responsible for encounter

Example Encounter Resource

{
  "resourceType": "Encounter",
  "id": "12345",
  "identifier": [{
    "use": "usual",
    "system": "http://hospital.example.org/encounters",
    "value": "ENC-2024-001"
  }],
  "status": "finished",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  },
  "type": [{
    "coding": [{
      "system": "http://snomed.info/sct",
      "code": "185349003",
      "display": "Encounter for check up"
    }]
  }],
  "subject": {
    "reference": "Patient/12345"
  },
  "participant": [{
    "type": [{
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
        "code": "ATND",
        "display": "attender"
      }]
    }],
    "individual": {
      "reference": "Practitioner/67890"
    }
  }],
  "period": {
    "start": "2024-01-15T09:00:00Z",
    "end": "2024-01-15T10:30:00Z"
  },
  "reasonCode": [{
    "coding": [{
      "system": "http://snomed.info/sct",
      "code": "162673000",
      "display": "General examination of patient"
    }]
  }],
  "serviceProvider": {
    "reference": "Organization/clinic-123"
  }
}

Supported Profiles

This API supports the following FHIR profiles:

• HL7 FHIR R4 Encounter

Operations

The General Purpose FHIR R4 Patient resource supports the following standard operations. However, support varies by the targeted CareRecord or solution.

CareRecord / Solution	Create	Read	Update	Search
GEHRIMED	-	Yes	-	Yes
myAvatar	Yes	Yes	Yes	Yes
myEvolv	-	Yes	-	Yes
myUnity	-	Yes	-	Yes
Referral Manager	-	-	-	-

Search

info

Not all Netsmart solutions support Encounter search. See supported operations table above and consult your target solution's documentation for more information.

This resource supports a combination of standard and custom search parameters in addition to the common parameters.

Standard Parameters

Name	Type	Description
date	date	A date within the period the Encounter lasted
episode-of-care	reference	Episode(s) of care that this encounter should be recorded against
patient	reference	REQUIRED The patient or group present at the encounter
status	token	arrived

Custom Parameters

Name	Type	Description
end	date	Deprecated. Use date parameter with le prefix instead.
start	date	Deprecated. Use date parameter with ge prefix instead.

Search Examples

The POST method is recommended as it keeps health information out of the URL.

Production

Search Program Admissions by Patient

curl -X POST https://fhir.netsmartcloud.com/v4/Encounter/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "patient=Patient/345" \
    -d "status=arrived"

Search Program Discharges by Patient

curl -X POST https://fhir.netsmartcloud.com/v4/Patient/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "patient=Patient/345" \
    -d "status=finished"

Preview

Search Program Admissions by Patient

curl -X POST https://fhirtest.netsmartcloud.com/v4/Encounter/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "patient=Patient/345" \
    -d "status=arrived"

Search Program Discharges by Patient

curl -X POST https://fhirtest.netsmartcloud.com/v4/Patient/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "patient=Patient/345" \
    -d "status=finished"

Special Considerations

The General Purpose API FHIR R4 Encounter resource has the following considerations in addition to the shared special considerations.

Status does not indicate Status

The HL7 FHIR Encounter concept encompasses multiple existing Netsmart concepts: Program Admission, Program Discharge, and Visit. This API has associated the Encounter.status with the following concepts to support ProviderConnect Enterprise workflows.

HL7 FHIR Status	Netsmart Concept	ID Prefix
arrived	Program Admission	arrived_
finished	Program Discharge	finished_

You would use the arrived status to see all admissions for a patient and then review the Encounter.period to determine whether the admission is still active or if the patient has been discharged. An additional search using the finished status will return additional discharge related content for those admission encounters.

Visit Encounters are not supported

Due to the Status exception described above this API is unable to support visit-related encounters.

Program Discharge Encounters must include the Program Admission Identifier

Program Discharge encounters provide additional content related to the discharge of an admission. This means we need to associate the Program Discharge encounter with the originating Program Admission encounter. This API supports this with an Identifier.

{
    "resourceType": "Encounter",
    "id": "finished_91||6546.61",
    "identifier": [
        {
            "use": "old",
            "system": "http://ntst.com/fhir/related-admission",
            "value": "arrived_3||6386.71"
        }
    ],
    "status": "finished",
    // additional Encounter content
}

myAvatar Encounter IDs are Not FHIR Conformant

As shown in previous examples, the IDs assigned to myAvatar Program Admissions and Discharges use || delimiters which are not allowed per the FHIR spec. This API allows them through however in newer APIs we will be replacing the || with -- to bring the IDs into conformance. This also applies to the ID prefix delimiter used on the API which in newer APIs replace _ with ...

If this is an issue with your FHIR Client then please consider using our Certified and Regulated APIs instead.

Error Handling

For information about error responses when working with Encounter resources, see Common Errors.

Common Encounter-related errors include:

• Missing required patient reference
• Invalid encounter status codes
• Malformed period dates
• Invalid participant or location references

Integration Patterns

Clinical Context

Encounters provide context for clinical activities:

# Get patient's recent encounters
curl -X GET "https://fhir.netsmartcloud.com/v4/Encounter?patient=12345&date=ge2024-01-01" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Program Management

Track program admissions and discharges:

# Get program admissions
curl -X GET "https://fhir.netsmartcloud.com/v4/Encounter?patient=12345&status=arrived" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

# Get program discharges
curl -X GET "https://fhir.netsmartcloud.com/v4/Encounter?patient=12345&status=finished" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Episode of Care Tracking

Link encounters to episodes of care:

# Get encounters for specific episode
curl -X GET "https://fhir.netsmartcloud.com/v4/Encounter?episode-of-care=EpisodeOfCare/67890" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Clinical Documentation

Retrieve encounter with related clinical data:

# Get encounter with diagnoses and procedures
curl -X GET "https://fhir.netsmartcloud.com/v4/Encounter/12345?_revinclude=Condition:encounter&_revinclude=Procedure:encounter" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Relationships to Other Resources

The Encounter resource serves as a central hub connecting many clinical resources:

• Patient - The individual receiving care during the encounter
• Practitioner - Healthcare providers participating in the encounter
• Organization - Healthcare organizations providing services
• Location - Physical locations where encounter takes place
• EpisodeOfCare - Episodes of care that encounters belong to
• Condition - Diagnoses made during encounters
• Procedure - Procedures performed during encounters
• Observation - Clinical observations made during encounters
• MedicationRequest - Medications prescribed during encounters
• CarePlan - Care plans developed during encounters
• Goal - Goals established during encounters

Support

For questions about Encounter resource implementation or clinical workflow integration, contact Netsmart support through your designated support channels.