Retrieve Encounter and Appointment resources for a patient's visit history
domain: fhir · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Search encounters: GET [base]/Encounter?patient=[id]&status=finished for completed visits; use status=in-progress for active encounters.
Filter by date: GET [base]/Encounter?patient=[id]&date=ge[YYYY-MM-DD] to limit to recent visits; the date parameter compares against Encounter.period.
Extract class.code for encounter class ('AMB' for ambulatory, 'IMP' for inpatient, 'EMER' for emergency) using the HL7 v3 ActCode system.
Read type[].coding for visit type (e.g., office visit CPT codes) and reasonCode[] for chief complaint or reason for visit codes.
For scheduled appointments, search Appointment: GET [base]/Appointment?patient=[id]&status=booked to retrieve upcoming appointments; status values include 'proposed', 'booked', 'arrived', 'fulfilled', 'cancelled'.
Link encounters to appointments via Appointment.basedOn or by correlating identifiers; not all servers populate this link.
Known gotchas
Encounter.period.start and .end may be in the server's local timezone without explicit offset; always parse as UTC or verify the server's timezone behavior.
Appointment and Encounter are separate resources and may not be linked; searching both independently is often required.
Some servers return only encounters from the patient's primary care context; encounters at other facilities may require queries to additional endpoints or consent-gated scopes.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?