Subscriptions API

Overview

Description

The Subscriptions API is used to manage a cohort of patients that you would like to receive ADT HL7v2 messages for. To start receiving notifications for a patient, create a new subscription with the patient_id. To stop receiving notifications for a patient, delete the subscription. Note that when you create and delete subscriptions, these changes will only be effective at the start of the following month.

Important Notes

  • A patient's demographics must be uploaded via the Patients API before a subscription can successfully be created.
  • You don't need to re-subscribe to notifications for a patient each month. If you don't explicitly unsubscribe from notifications for a patient, the subscription will carry over to the next month.

API Endpoints

Subscribe to ADT Notifications for a Patient

Description:Subscribe to ADT notifications for a patient.
Path:api/v1/subscriptions/adt/{patient_id}
Method:POST

Example Request

curl -X POST -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v1/subscriptions/adt/{patient_id}

Response Model

{
    "SubscriptionID": "example-subscription-id",
    "PatientID": "example-patient-id",
    "SubscriptionType": "ADT",
    "State": "SUBSCRIBE_PENDING",
    "Created": "2022-01-01T00:00:00.000000Z",
    "Updated": "2022-01-01T00:00:00.000000Z",
}

Unsubscribe from ADT Notifications for a Patient

Description:Stop receiving ADT notifications for a patient.
Path:api/v1/subscriptions/adt/{patient_id}
Method:DELETE

Example Request

curl -X DELETE -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v1/subscriptions/adt/{patient_id}

Response Model

“delete successful”

Retrieve Subscription State

Description:Retrieve the subscription state for a patient.
Path:api/v1/subscriptions/adt/{patient_id}
Method:GET

Example Request

curl -X GET -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v1/subscriptions/adt/{patient_id}

Response Model

{
    "SubscriptionID": "example-subscription-id",
    "PatientID": "example-patient-id",
    "SubscriptionType": "ADT",
    "State": "SUBSCRIBE_PENDING",
    "Created": "2022-01-01T00:00:00.000000Z",
    "Updated": "2022-01-01T00:00:00.000000Z",
}

Subscription States

Subscription StateDescriptionWill I Receive ADT Events?
SUBSCRIBE_PENDINGSubscription is being reviewed by Particle. This will typically take 1-2 days.No
SUBSCRIBEDSubscription is approved. You will begin to receive ADT messages for the patient.Yes
UNSUBSCRIBEDSubscription is cancelled. You will no longer receive ADT messages for the patient.No