API for the Exchange of Medicinal Product Information (APIX)
0.1.0 - ci-build International flag

API for the Exchange of Medicinal Product Information (APIX), published by HL7 International / Biomedical Research and Regulation. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/APIX---API-Exchange-for-Medicinal-Products/ and changes regularly. See the Directory of published versions

Subscription

Page standards status: Informative

Subscription

The Subscription resource delivers real-time notifications when regulatory events occur — task status changes, new assignments, and decisions.

For Business Readers

A Subscription is like a notification rule. You tell the FHIR server: "Notify me when this specific Task changes status" or "Notify me when the regulator creates a new Task assigned to my organization." The server automatically sends a webhook notification every time the condition is met — no polling required.

In APIX, the Subscription resource is the mechanism that delivers real‑time notifications when regulatory events occur. A Subscription becomes active when:

  1. The event matches the trigger defined in the SubscriptionTopic, and
  2. The resource involved satisfies the Subscription.filterBy constraints.

When both conditions are met, the server sends a notification bundle to the subscriber’s configured Subscription.endpoint.

APIX uses Subscriptions for two primary regulatory event types:

  • Task Status Change — filtered by Task.identifier
    Notifies the requester when the regulator updates the status of a Task (e.g., received → accepted, in‑progress → on‑hold, completed).

  • Task Creation — filtered by Task.owner
    Notifies an Organization when the regulator creates a new Task for them (e.g., questions, decision letters, follow‑up actions).

These two patterns allow APIX participants to receive immediate, event‑driven updates without polling.

Example Subscription

For more information on how this ties into Subscriptions see: Real-time Subscriptions

Key Elements of the APIX Subscription Resource

Element Cardinality (APIX) Value / Example Purpose / Notes
Subscription.filterBy 0..* • filterParameter = identifier or owner
• value = e.g. Organization/1001		 Defines the subset of events the subscriber is interested in (e.g., Tasks for a specific organization or Tasks with a specific identifier)
Subscription.topic 1..1 Canonical URL of the SubscriptionTopic
e.g. http://myfhir/fhir/SubscriptionTopic/TaskStatusChangeWithIdentifierFilter		 Must exactly match the SubscriptionTopic.url that governs the event type and trigger logic
Subscription.endpoint 1..1 REST‑hook endpoint URL
e.g. https://hapi.requestcatcher.com/		 Destination where event notifications are delivered
Subscription.reason 1..1 Human‑readable explanation
e.g. “Notify Organization when a new Task is assigned”		 Describes the business purpose for auditability and transparency
Subscription.managingEntity 0..1 Reference(Organization)
e.g. Organization/1001		 Identifies the organization responsible for maintaining the subscription