Subscriptions API

Overview

The Subscriptions API is used to create and manage a cohort of patients that you would like to monitor for new patient encounters and/or ADT HL7v2 messages. To start receiving notifications for a patient, you’ll need to create a new subscription for the patient with the particle_patient_id.

Important Notes

  • A Particle Patient ID must be generated for a patient by uploading the patient's demographics via the Patients API before a subscription can successfully be created for the patient
  • You can opt to subscribe to monitoring notifications for a cohort of patients or for a single patient. You can subscribe to multiple types of notifications for the same patient.
  • If you want to stop monitoring a patient, you can unsubscribe from notifications for that patient using the Delete Patient Subscriptions API; do not delete the patient from the Patients API. Note that when you create and delete subscriptions, ADT notifications these changes will only be effective at the start of the following month.
  • 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.

Creating Patients

You’ll first need to record for each patient you want to monitor via the Patients API, and store the Particle Patient ID returned in the response. Below is an example of the response returned from the API call:

{
	"given_name":"Travis",
	"family_name":"Bogisich",
	"date_of_birth":"1980-11-05",
	"gender":"MALE",
	"ssn":"",
	"email":"[email protected]",
	"address_lines":["950 Braun Path"],
	"address_state":"MN",
	"address_city":"Rochester",
	"postal_code":"55901",
	"telephone":"(404) 555-1234",
	"patient_id":"843579fd-24ac-4263-8ad1-3e55a9152da0",
	"particle_patient_id":"95e7dde6-7b20-4842-8dff-962a405a858b"
}

Subscribe to Notifications

Once you’ve created patient records via the Patients API, you can subscribe to monitoring notifications for the patients. There are 3 types of monitoring notifications. You can create subscriptions to multiple types of notifications for the same patient.*

Notification TypeDescription
Proactive QueryingFor each patient in the cohort, Particle establishes a map of a patient's provider network. We monitor and intelligently query the patient-provider map for new encounters, and notify you when new data is available.
Network AlertsParticle tracks alerts of new patient encounters on the networks. We query for new data generated from these encounters and notify you when new data is available.
ADTsWhen a patient is admitted, transferred, discharged, or deceased at an Admitting Facility in the Particle community, the customer will receive a real-time HL7v2 ADT notification about the patient's care encounter.

*Your organization must be configured with the right access to subscribe to each notification type. Reach out to your Particle team if you have any questions on the type(s) of notifications you can subscribe to.

➡️

NOTE when you subscribe to ADTs for a patient, ADT monitoring for that patient will start from the 1st of the following month. For example, if a patient subscription is created on January 5th, monitoring will start on February 1st.

When you subscribe to monitoring for new encounters a patient, monitoring starts immediately, with an initial query executed for the patient within 48 hours.

Create Subscriptions for a Cohort of Patients

To create subscriptions to notifications for a cohort of patients, you will need to provide the Particle Patient ID and specify the type of notifications that you would like to subscribe to, as well as the desired start date and end date, for each patient in the cohort.

You also can place a single request to create subscriptions for a cohort to multiple types of notifications (e.g., ADTs, Network Alerts, and Proactive Querying). Alternatively, you can place individual requests for each cohort of patients that you want to subscribe to a given type of notifications. For example, you can place a request that includes the cohort of patients for whom you want to receive ADTs, and a separate request to indicate the cohort of patients for whom you want to receive Network Alerts. Examples of both workflows are included below.

Description:Subscribe a cohort of patients to monitor for network alerts, proactive querying, and/or ADT notifications
Path:api.particlehealth.com/api/v1/patients/subscriptions
Method:POST

Example Request - Subscribing a Cohort to Network Alerts

curl --request POST \
     --url https://api.particlehealth.com/api/v1/patients/subscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Example Request Body - Subscribing a Cohort to Network Alerts

{
 "subscriptions":[
		{
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"particle_patient_id": "95e7dde6-7b20-4842-8dff-962a405a858b"
		},
		{
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"particle_patient_id": "4b7e786c-bfdf-4d11-bf68-99a347d4b934"
		}
	]
}

Example Response- Subscribing a Cohort to Network Alerts

{
 "subscriptions":[
		{
			"id": "67aeafc6-cc89-4a00-8202-3da0d49c676e",
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"particle_patient_id": "95e7dde6-7b20-4842-8dff-962a405a858b"
			"state": "subscribed"
		},
		{
			"id": "cd2d57ca-d73a-47eb-a069-a700562f19a2",
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"particle_patient_id": "4b7e786c-bfdf-4d11-bf68-99a347d4b934"
			"state": "subscribed"
		}
	]

Example Request - Subscribing a Cohort to Multiple Subscriptions

curl --request POST \
     --url https://api.particlehealth.com/api/v1/patients/subscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Example Request Body - Subscribing a Cohort to Multiple Subscriptions

{
 "subscriptions":[
		{
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"particle_patient_id": "95e7dde6-7b20-4842-8dff-962a405a858b"
		},
		{
			"type": "PROACTIVE_QUERYING",
			"start_date": "2024-01-01",
			"end_date": "2025-01-01",
			"particle_patient_id": "95e7dde6-7b20-4842-8dff-962a405a858b"
		},
		{
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"particle_patient_id": "4b7e786c-bfdf-4d11-bf68-99a347d4b934"
		}
	]
}

Example Response - Subscribing a Cohort to Multiple Subscriptions

{
 "subscriptions":[
		{
			"id": "67aeafc6-cc89-4a00-8202-3da0d49c676e",
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"particle_patient_id": "95e7dde6-7b20-4842-8dff-962a405a858b"
			"state": "subscribed"
		},
		{
			"id": "90ed4f35-72fe-4083-a347-a30cf452f89f",
			"type": "PROACTIVE_QUERYING",
			"start_date": "2024-01-01",
			"end_date": "2025-01-01",
			"particle_patient_id": "95e7dde6-7b20-4842-8dff-962a405a858b"
			"state": "subscribed"
		},
		{
			"id": "cd2d57ca-d73a-47eb-a069-a700562f19a2",
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"particle_patient_id": "4b7e786c-bfdf-4d11-bf68-99a347d4b934"
			"state": "subscribed"
		}
	]

Error Response (Validation Failures)

{
 "subscriptions":[
		{
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-02-31",
			"particle_patient_id": "95e7dde6-7b20-4842-8dff-962a405a858b"
			"error": "end_date is invalid"
		},
		{
			"type": "PROACTIVE_QUERYING",
			"start_date": "2024-02-01",
			"end_date": "2024-01-01",
			"particle_patient_id": "95e7dde6-7b20-4842-8dff-962a405a858b"
			"error": "end_date should be after start_date"
		},
		{
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"particle_patient_id": "12345",
			"error": "particle patient id 12345 does not exist "
		}
	]
}

Create Subscriptions for an Individual Patient

If preferred, you have the option of subscribing individual patients. The same data (Particle Patient ID, start date, end date, type) is required to create an individual subscription. You can create multiple subscriptions, to different types of notifications, for a single patient.

Subscriptions for a single patient can be managed independently, by placing a request per type of subscription that you want to create (e.g., NETWORK_ALERT vs. ADT). Alternatively, you can place a single request to create multiple subscriptions for a single patient.

Description:Subscribe a single patient to monitor for network alerts, proactive querying, and/or ADT notifications
Path:api.particlehealth.com/api/v1/patients/{particle_patient_id}/subscriptions
Method:POST

Example Request

curl --request POST \
     --url api.particlehealth.com/api/v1/patients/{particle_patient_id}/subscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Request Body

{
    "subscriptions": [
        {
            "type": "NETWORK_ALERT",
						"start_date": "2024-01-01",
						"end_date": "2024-12-31"
        },
        {
            "type": "PROACTIVE_QUERYING",
						"start_date": "2024-01-01",
						"end_date": "2024-12-31"
        }
    ] 
}

Response Model

{
 "subscriptions":[
		{
			"id": "67aeafc6-cc89-4a00-8202-3da0d49c676e",
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"state": "subscribed"
		},
		{
			"id": "90ed4f35-72fe-4083-a347-a30cf452f89f",
			"type": "PROACTIVE_QUERYING",
			"start_date": "2024-01-01",
			"end_date": "2024-12-31",
			"state": "subscribed"
		}
	]
}

Error Response (Validation Error)

{
 "subscriptions":[
		{
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2024-02-31",
			"error": "end_date is invalid"
		},
		{
			"type": "PROACTIVE_QUERYING",
			"start_date": "2024-02-01",
			"end_date": "2024-01-01",
			"error": "end_date should be after start_date"
		}
	]
}

Unsubscribe from Notifications for a Patient

If you want to stop monitoring a patient, you can unsubscribe from notifications for that patient using Delete Patient Subscriptions; do not delete the patient from the Patients API.

Note that when you create and delete subscriptions, for ADT notifications, these changes will only be effective at the start of the following month.

Description:Stop receiving network alerts, proactive querying, and/or ADT notifications for a patient
Path:api.particlehealth.com/api/v1/patients/{particle_patient_id}/subscriptions
Method:DELETE

Example Request

curl --request DELETE \
     --url https://api.particlehealth.com/api/v1/patients/{particle_patient_id}/subscriptions \
     --header 'accept: application/json'

Response Model

No response expected. If subscriptions were successfully deleted HTTP status 204 code is
returned.

Update Patient Subscription Period

If you want to update the subscription period for a patient (i.e., the period of time for which you want to receive notifications for the patient), you can use the Update Patient Subscription Period APIs to pass updated start and end dates. You will need to pass the subscription_id of the subscription that you want to update for the patient.

📌 Note if you want to stop receiving notifications for a patient entirely, use the [Delete Patient Subscriptions API](). If you want to subscribe to a new type of notification for a given patient, use the [Create Patient Subscriptions API]() to create a new subscription for the patient.
Description:List all subscriptions, and the state of each subscription, for a given patient
Path:api.particlehealth.com/api/v1/patients/{particle_patient_id}/subscriptions/{subscription_id}
Method:PATCH

Example Request

curl --request PATCH \
     --url https://api.particlehealth.com/api/v1/patients/id/subscriptions/subscription_id \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Request Body

{
  "start_date": "2024-03-01",
	"end_date": "2025-05-01"
}

Response Model

{
	"id": "90ed4f35-72fe-4083-a347-a30cf452f89f",
	"type": "PROACTIVE_QUERYING",
	"start_date": "2024-01-01",
	"end_date": "2025-01-01",
	"state": "subscribed"
}

List Patient Subscriptions

You can call the List Patient Subscriptions API to retrieve a list of all subscriptions for a given patient, including the subscription type, state, and start and end dates.

Description:List all subscriptions, and the state of each subscription, for a given patient
Path:api.particlehealth.com/api/v1/patients/{particle_patient_id}/subscription
Method:GET

Example Request

curl --request GET \
     --url https://api.particlehealth.com/api/v1/patients/{particle_patient_id}/subscriptions \
     --header 'accept: application/json'

Response Model

{
 "subscriptions":[
		{
			"id": "67aeafc6-cc89-4a00-8202-3da0d49c676e",
			"type": "NETWORK_ALERT",
			"start_date": "2024-01-01",
			"end_date": "2025-01-01",
			"state": "subscribed"
		},
		{
			"id": "90ed4f35-72fe-4083-a347-a30cf452f89f",
			"type": "PROACTIVE_QUERYING",
			"start_date": "2024-01-01",
			"end_date": "2025-01-01",
			"state": "subscribed"
		}
	]
}

Subscription States

Subscription StateDescriptionWill I Receive Notifications?
SUBSCRIBE_PENDINGSubscription is being reviewed by Particle. This will typically take 1-2 days. Note this review window is only applicable for ADTs, to account for partner requirements.No
SUBSCRIBEDSubscription is approved. You will begin to receive notifications for the patient.Yes
UNSUBSCRIBEDSubscription is cancelled. You will no longer receive notifications for the patient.No

FAQ

Do I have to specify the start_date and end_date for each subscription that I create for a patient?

The start_date and end_date parameters are optional, so you do not need to specify these values in the API call to create a subscription for a patient. These parameters are required by our ADT partners to subscribe to ADTs for patients, however, which is why we request them.

If you do not specify a value, we will default to the current date for the start_date. For the end_date, we will default to 100 years from current date.