Encounter

Overview

The Encounter resource provides "an interaction between a patient and healthcare provider(s) for the purpose of providing healthcare service(s) or assessing the health status of a patient." This resource captures the details of healthcare encounters including visits, appointments, and other interactions between patients and healthcare providers.

Resource Schema

Key fields in the Encounter resource:

{
  "resourceType": "Encounter",
  "id": "example-encounter",
  "status": "finished",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  },
  "subject": {
    "reference": "Patient/123"
  },
  "period": {
    "start": "2023-01-15T10:00:00Z",
    "end": "2023-01-15T11:00:00Z"
  },
  "participant": [{
    "individual": {
      "reference": "Practitioner/456"
    }
  }]
}

Operations

The Encounter resource supports the following operations:

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

Read

Retrieve a specific encounter by ID.

Production

GET /Encounter/{id}

Example Request

curl -X GET https://fhir.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Encounter/encounter-123 \
    -H "Accept: application/fhir+json"

Preview

GET /Encounter/{id}

Example Request

curl -X GET https://fhirtest.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Encounter/encounter-123 \
    -H "Accept: application/fhir+json"

Search

Search for encounters using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production

GET /Encounter?parameter=value

Preview

GET /Encounter?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production

POST /Encounter/_search

Preview

POST /Encounter/_search

Search Parameters

Patient-based Search:

Parameter	Type	Required	Description	Example
patient	reference	Yes	The patient or group present at the encounter	patient=value
date	date	No	A date within the period the Encounter lasted	date=value
status	token	No	planned	status=value
_lastUpdated	date	No	Only return resources which were last updated as specified by the given range	_lastUpdated=value

ID-based Search:

Parameter	Type	Required	Description	Example
_id	string	Yes	The ID of the resource	_id=value
_lastUpdated	date	No	Only return resources which were last updated as specified by the given range	_lastUpdated=value

Examples

Search by Patient and Date

Production

curl -X POST https://fhir.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Encounter/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "patient=Patient/123" \
    -d "date=ge2023-07-10"

Preview

curl -X POST https://fhirtest.netsmartcloud.com/payer/system-access/v2/Encounter/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "patient=Patient/123" \
    -d "date=ge2023-07-10"

Integration Patterns

Common Workflows

1. Patient Visit History

# Step 1: Get all encounters for patient
GET /Encounter?patient=Patient/patient-123

# Step 2: Filter by date range
GET /Encounter?patient=Patient/patient-123&date=ge2023-01-01&date=le2023-12-31

# Step 3: Get specific encounter details
GET /Encounter/encounter-456

2. Care Episode Analysis

# Step 1: Find recent encounters
GET /Encounter?patient=Patient/patient-123&status=finished&_count=5

# Step 2: Get conditions from encounters
GET /Condition?encounter=Encounter/encounter-456

# Step 3: Get procedures performed
GET /Procedure?encounter=Encounter/encounter-456

Related Resources

• Patient - Individual present at the encounter
• Condition - Diagnoses made during the encounter
• Procedure - Procedures performed during the encounter
• Observation - Clinical observations from the encounter
• Practitioner - Healthcare providers involved in the encounter

Error Handling

The Encounter resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.

Encounter-Specific Error Scenarios

• 404 Not Found: Encounter ID doesn't exist or encounter record is inactive
• 400 Bad Request: Invalid search parameters or malformed date formats
• Empty Results: No encounters match the search criteria

Troubleshooting Tips

• No Results for Patient: Verify patient reference format and ensure patient exists
• Date Range Issues: Ensure dates are in YYYY-MM-DD or ISO 8601 format
• Status Problems: Use valid encounter status codes (planned, finished, cancelled)
• Performance Issues: Use _count parameter to limit result sets

Supported Profiles

This API supports the following FHIR profiles:

• US Core Encounter