Profiles & Operations > Interaction: Search Subscriptions

Search Subscriptions

The Search Subscriptions interaction allows an Electronic Medical Record (EMR) system to retrieve all active Subscriptions it has previously created. This interaction is aligned with the FHIR R5 Subscription Backport model.

The requesting EMR is identified by a unique emr_id, passed as a search parameter. The server returns a Bundle of type searchset containing matching Subscription resources.

Usage

Search Subscription Request

The Search Subscription shall retrieve all FHIR Subscription resource from the repository created by specific EMR instance.


  'GET \[base]/Subscription?emr_id=[EMR_ID]'

Search Parameter

Name Type Cardinality Description
emr_id token 1..1 Unique identifier for the EMR that owns the subscription. Filtered against meta.tag.code.

Note: The emr_id parameter is a custom search parameter mapped to Subscription.meta.tag.

Search Subscription Response

  • The server returns a 200 OK HTTP status code.

  • The response bodfy contains FHIR Resource Type: Bundle (type = searchset)

  • Each entry.resource is a Subscription that matches the provided emr_id.

Interaction Sequence Diagram

search_subscriptions

Example Search Subscriptions Interaction

Example Search Subscriptions Request

GET [base]/Subscription?emr_id=EMR-12345]

POST method can be used when search parameters are too complex or long for a URL (e.g., long queries or special characters). Parameters are passed in the body as application/x-www-form-urlencoded.

POST [base]/Subscription/_search
Content-Type: application/x-www-form-urlencoded

Example Search Subscriptions Response Body

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "entry": [
    {
      "resource": {
        "resourceType": "Subscription",
        "id": "sub-001",
        "status": "active",
        "criteria": "Patient?identifier=12345",
        "channelType": {
          "code": "rest-hook"
        },
        "endpoint": "https://emr.example.org/notify",
        "content": "id-only",
        "meta": {
          "tag": [
            {
              "system": "https://healthauthority.ca/fhir/emr-id",
              "code": "EMR-12345"
            }
          ]
        }
      }
    },
    {
      "resource": {
        "resourceType": "Subscription",
        "id": "sub-002",
        "status": "active",
        "criteria": "Encounter?status=planned",
        "channelType": {
          "code": "rest-hook"
        },
        "endpoint": "https://emr.example.org/notify",
        "content": "id-only",
        "meta": {
          "tag": [
            {
              "system": "https://healthauthority.ca/fhir/emr-id",
              "code": "EMR-12345"
            }
          ]
        }
      }
    }
  ]
}

Security & Authorization

  • Access to this interaction is restricted to authorized EMRs.
  • OAuth2 authentication is required.
  • Only subscriptions tagged with the authenticated EMR's emr_id will be returned.

Error Handling

HTTP Status Reason Description
400 Missing or invalid emr_id parameter The required search parameter is not valid.
401 Unauthorized Request is missing a valid access token.
500 Internal Server Error A server-side error occurred.

Notes

  • Subscriptions are filtered using meta.tag.code to match the provided emr_id.
  • This interaction supports the use case of allowing EMRs to view and manage their registered topics/subscriptions.
  • Subscription resources returned conform to the R5 Subscription Backport Profile.