HL7 APR Segment: Appointment Preferences

The APR (Appointment Preferences) segment carries the preference criteria a placer attaches to a scheduling request so a filler application can choose the best time, resource, and location for an appointment. It expresses how the requester wants the slot found rather than the appointment itself: time windows, resource ranking, location ranking, the minimum spacing between candidate slots, and any filler override rules. APR is a companion to the ARQ request segment and the SCH scheduling segment, and it shares the same scheduling vocabulary used across the sch-appointments group.

Purpose

APR lets a placer guide an automated or assisted scheduling search. Where ARQ states the appointment that is wanted, APR states the rules for selecting candidate slots. A filler engine reads APR to rank or filter the slots it returns, honoring preferred times, preferred or required resources, preferred locations, the spacing it should leave between offered slots, and whether the filler may override the placer's stated constraints. Because every selection-criteria field uses the SCV (Scheduling Class Value Pair) data type, each preference is encoded as a parameter/value pair that the receiving engine interprets against its own scheduling rules.

Used in

APR appears in scheduling messages on both sides of the request/response exchange:

SRM (Schedule Request Message) — a placer includes APR after ARQ to qualify the requested appointment with preference criteria.
SIU (Unsolicited Scheduling Information) — a filler includes APR to communicate the preferences that were applied when booking or modifying an appointment. See /academy/hl7/messages/siu.

In both message types APR is optional and may repeat per appointment request grouping. It travels alongside the RGS resource group and the resource segments (AIG/AIL/AIP/AIS) that describe what is being scheduled.

Field-by-field reference

Source: HAPI HL7v2 v2.5.1 javadocs (APR javadoc) for sequence, name, data type, and repetition. Length is not published in the javadocs (—); Required and Table # are filled from the HL7 v2.5.1 standard where well-established.

Seq	Name	Data Type	Length	Req	Repeat	Table #	Description
APR-1	Time Selection Criteria	scv	—	O	Y	—	Preferred day and time-of-day windows for slots
APR-2	Resource Selection Criteria	scv	—	O	Y	—	Preferred or required resources for the appointment
APR-3	Location Selection Criteria	scv	—	O	Y	—	Preferred or required locations for the appointment
APR-4	Slot Spacing Criteria	nm	—	O	—	—	Minimum spacing between candidate slots offered
APR-5	Filler Override Criteria	scv	—	O	Y	—	Rules letting filler override placer constraints

Most-used fields

APR-1 Time Selection Criteria — the most common APR field; placers use it to restrict offered slots to preferred days of the week, parts of the day, or explicit time ranges. Each repetition is one parameter/value pair (for example PreferredStartTime paired with a value).
APR-2 Resource Selection Criteria — names a preferred or required resource (a person, room, or equipment) so the filler can rank candidate slots that include that resource. This often pairs with the resource segments under RGS.
APR-3 Location Selection Criteria — narrows candidate slots to preferred or required locations, useful for multi-site organizations.
APR-4 Slot Spacing Criteria — a single numeric value telling the filler the minimum gap to leave between the slots it offers, so a list of candidates is not clustered.

Version differences (2.3 to 2.8.2)

2.3 — APR was introduced with the scheduling chapter (Chapter 10). The five-field structure (time, resource, location, slot spacing, filler override) has been stable since introduction.
2.4 / 2.5 / 2.5.1 — No structural change to APR. The SCV data type and its parameter/value semantics are carried forward unchanged; this page documents the 2.5.1 form.
2.6 / 2.7 / 2.8 / 2.8.2 — APR remains a five-field segment. Later versions refine wording and the underlying SCV component definitions but do not add or remove APR fields. Engines that target newer versions can treat APR identically to 2.5.1 for these fields.

The normalized takeaway: APR is one of the most stable scheduling segments — five fields across every modern version. Treat field order and the SCV/NM types as fixed.

Common mistakes

Treating selection criteria as free text. APR-1, APR-2, APR-3, and APR-5 are SCV (parameter/value) pairs, not plain strings. Encode a parameter name and its value, not a sentence.
Putting the appointment itself in APR. The requested appointment time, type, and duration belong in ARQ, not APR. APR only expresses how to select among candidate slots.
Forgetting repetition. APR-1, APR-2, APR-3, and APR-5 repeat. Sending multiple preferences concatenated into one repetition instead of separate repetitions breaks downstream parsing.
Assuming the filler must obey APR. Preferences are advisory unless paired with filler override rules in APR-5. A filler may return slots that do not satisfy every stated preference.
Sending APR without ARQ. In an SRM request, APR is meaningless on its own; it qualifies a preceding ARQ request.

Examples

Minimal

APR|^PreferredDay^Weekday

Fully populated

APR|^PreferredDay^Weekday~^PreferredTime^Morning|^Resource^RES-MRI-02|^Location^EAST-CLINIC|15|^AllowOverride^N

Annotated breakdown

APR|^PreferredDay^Weekday~^PreferredTime^Morning|^Resource^RES-MRI-02|^Location^EAST-CLINIC|15|^AllowOverride^N
    |                                            |                    |                     |  |
    |                                            |                    |                     |  └─ APR-5 Filler Override Criteria (SCV): override not allowed
    |                                            |                    |                     └──── APR-4 Slot Spacing Criteria (NM): 15-minute minimum spacing
    |                                            |                    └────────────────────────── APR-3 Location Selection Criteria (SCV): prefer EAST-CLINIC
    |                                            └─────────────────────────────────────────────── APR-2 Resource Selection Criteria (SCV): prefer resource RES-MRI-02
    └──────────────────────────────────────────────────────────────────────────────────────────  APR-1 Time Selection Criteria (SCV), repeating:
                                                                                                   rep 1 -> PreferredDay = Weekday
                                                                                                   rep 2 -> PreferredTime = Morning

In context — SRM^S01 schedule request

MSH|^~&|SCHEDAPP|EAST-CLINIC|FILLER|EAST-CLINIC|20260610093000||SRM^S01^SRM_S01|MSG00231|P|2.5.1
ARQ|PLAC-77821^EAST-CLINIC||1||SCHED-RAD^Radiology^L|||MRI^MRI Brain^L|30|MIN^minutes^UCUM|20260618080000^20260618170000
APR|^PreferredDay^Weekday~^PreferredTime^Morning|^Resource^RES-MRI-02|^Location^EAST-CLINIC|15|^AllowOverride^N
RGS|1|A|RG-MRI^MRI Group^L
AIG|1|A|RES-MRI-02^MRI Scanner 2^L|EQUIP

In context — SIU^S12 booked notification

MSH|^~&|FILLER|EAST-CLINIC|EHR|EAST-CLINIC|20260610101500||SIU^S12^SIU_S12|MSG00232|P|2.5.1
SCH|PLAC-77821^EAST-CLINIC|FILL-55012^EAST-CLINIC|||SCHED-RAD^Radiology^L|MRI^MRI Brain^L||30|MIN^minutes^UCUM|^^^20260618083000^20260618090000
APR|^PreferredTime^Morning|^Resource^RES-MRI-02|^Location^EAST-CLINIC|15|^AllowOverride^N
RGS|1|A|RG-MRI^MRI Group^L
AIG|1|A|RES-MRI-02^MRI Scanner 2^L|EQUIP

FHIR mapping

Source	Target	Notes
APR	Not mapped at the segment level	No segment-level ConceptMap is published in the v2-to-FHIR IG for APR. Scheduling data maps conceptually to the FHIR Appointment, Schedule, and Slot resources.

In practice, APR's preference criteria do not have a direct FHIR target. The intent behind the criteria most often informs how candidate FHIR Slot resources are searched and how the resulting Appointment is constructed, but the criteria themselves are not carried as discrete FHIR elements.

Engine considerations

Most integration engines pass APR through as repeating SCV fields without interpreting the parameter names. If your filler logic must honor preferences, add explicit rules keyed on the SCV parameter component.
Validate that APR follows an ARQ within the same request grouping; an orphan APR usually indicates a message construction bug.
When APR-1, APR-2, APR-3, or APR-5 repeat, preserve repetition delimiters (~) on transform — flattening them into a single value loses preferences.
APR-4 is numeric; reject non-numeric values early rather than passing them downstream.

How Vorro parses and produces APR

When parsing, Vorro reads each APR field by sequence, splitting the repeating SCV fields (APR-1, APR-2, APR-3, APR-5) into individual parameter/value pairs and exposing each as a normalized preference object. APR-4 is parsed as a number. Vorro associates the parsed APR with the preceding ARQ so preferences stay bound to their request.

When producing APR, Vorro serializes preference objects back into SCV repetitions in field order, emits APR-4 as a plain numeric value, and only writes a field when a preference is present — empty preference fields are left blank rather than padded. The output is consistent with the SCH and RGS segments produced in the same message.

Sources

← Back to HL7 v2 Guide