Timeline Events | Referral Exchange docs

RefX uses timeline events to provide an audit trail of referrals. Every significant action from referral creation to note submission, appointment confirmation, amendment, and cancellation, etc. generates a structured event. These events allow both sender and receiver systems to reconstruct the entire journey of a referral and maintain compliance with audit and traceability requirements.

How it works

Each referral record contains an array of timelineEvents, each including:

Field	Description
type	The event type (e.g. `referral.created`, `appt.confirmed`, `note.created`)
description	A human-readable explanation, suitable for display in a user interface
system	Which system triggered the event (e.g. HAS, PartnersBuddy, Epic)
producedAt	Timestamp (in milliseconds since epoch) when the event occurred

Implementation notes

Displaying events:

Use timeline events to build an activity feed within your system.

Group them by date, and display the most recent actions at the top using the description field.

Example:
```
12 Jan 2025
- HAS confirmed appointment at 9:00 AM
- Dr. Tan added a note: “Please check blood sugar results before appt.”
```
Try not to rely on the type field as there may be new timeline event types added in the future. Using the description field allows you to display meaningful information to users without needing to update your system for new event types.
Asynchronous updates: Timeline events are the most reliable indicator of referral progress. If your system detects new events, re-fetch the referral details to reflect the latest state.
System mapping: The system field helps distinguish between user-driven and automated actions. This is useful for debugging or understanding cross-system interactions.
Retention: Timeline events are immutable and persist as part of the referral’s permanent record. They should not be deleted or edited once created.