Viewing Encounters
Transform raw encounter data into patient timelines, appointment calendars, and visit summaries.
1. Understanding Encounters
An encounter represents a scheduled or completed interaction between a patient and provider. Guardian Health maps upstream visit types into normalized categories: office visit, telehealth, emergency, inpatient, and outpatient.
- Scheduled – Future visit with expected start/end times.
- In-progress – Visit currently underway.
- Completed – Visit finished; includes actual timing and notes.
- Cancelled – Visit cancelled by the patient or provider.
2. Retrieving Encounter Data
Start by fetching encounters scoped to a patient. Use filters for status and date range to narrow the list for dashboards or patient portals.
List encounters for a patient
Retrieve the latest 10 encounters for a patient.
curl "https://api.guardianhealth.dev/api/v1/encounters?patient_id=c2f1a6fa-4d93-4d37-a8d8-56b6b6a2f94f&limit=10" \\\n -H "Authorization: Bearer $GUARDIAN_API_KEY"Filter by date range
Python example for retrieving encounters completed in October 2024.
import os
import requests
params = {"status": "completed", "start_date": "2024-10-01", "end_date": "2024-10-31"}
response = requests.get(
"https://api.guardianhealth.dev/api/v1/encounters",
params=params,
headers={"Authorization": f"Bearer {os.environ["GUARDIAN_API_KEY"]}"}
)
response.raise_for_status()
for encounter in response.json()["data"]:
print(encounter["scheduled_start"], encounter["status"])3. Working with Encounter Details
Each encounter includes clinical notes, chief complaints, and actual timing (when available). Use this data to build comprehensive visit summaries.
Encounter example
Successful response codes: HTTP 200
{
"id": "84c61d52-2b54-4542-bc88-bf8f8e8c420b",
"patient_id": "c2f1a6fa-4d93-4d37-a8d8-56b6b6a2f94f",
"encounter_type": "office-visit",
"status": "completed",
"scheduled_start": "2024-10-21T16:00:00Z",
"scheduled_end": "2024-10-21T16:30:00Z",
"actual_start": "2024-10-21T16:05:12Z",
"actual_end": "2024-10-21T16:33:44Z",
"chief_complaint": "Persistent migraine with aura",
"notes": "Patient responded well to nerve block therapy.",
"location": "Guardian Health Ballard Clinic"
}4. Filtering by Provider
Provider calendars often require filtering by provider ID and status. The example below returns scheduled visits for a given provider.
Provider schedule snippet
JavaScript helper for building provider calendars.
const providerId = '93fa7244-716a-40bc-a75a-a854b913d553';\nconst params = new URLSearchParams({ provider_id: providerId, status: 'scheduled' });\nconst response = await fetch(`https://api.guardianhealth.dev/api/v1/encounters?${params.toString()}`, {\n headers: { Authorization: `Bearer ${process.env.GUARDIAN_API_KEY}` }\n});\nif (!response.ok) throw new Error('Failed to fetch encounters');\nconst { data } = await response.json();\nreturn data.map((encounter) => ({\n start: encounter.scheduled_start,\n end: encounter.scheduled_end,\n patientId: encounter.patient_id\n}));5. Building Encounter Views
Visualize encounter data as chronological timelines or appointment cards. The React component below renders a simple timeline list.
React encounter timeline
Render an ordered timeline of encounters with status and chief complaint.
import { format, parseISO } from 'date-fns';\n\nfunction EncounterTimeline({ encounters }) {\n return (\n <ol className="space-y-4">\n {encounters.map((encounter) => (\n <li key={encounter.id} className="rounded-lg border border-slate-200 bg-white p-4 shadow-sm">\n <p className="text-sm font-medium text-slate-500">\n {format(parseISO(encounter.scheduled_start), 'PPpp')} — {encounter.encounter_type.replace('-', ' ')}\n </p>\n <p className="text-slate-700">Status: {encounter.status}</p>\n <p className="text-slate-600">Chief complaint: {encounter.chief_complaint ?? 'N/A'}</p>\n </li>\n ))}\n </ol>\n );\n}\n\nexport default EncounterTimeline;