This guide walks you through how to use Particle Signal to monitor patient transitions and retrieve associated clinical data. Transition Alerts include notifications for patient admissions, discharges, and upcoming support for episodes of care.

What is a Transition Alert?

Transition Alerts provide critical, timely notifications about significant changes in a patient's care setting or status. These alerts are intelligently derived from a sophisticated analysis of patient activity across national and state health information networks, offering a consolidated and actionable signal of a patient moving between different care environments or statuses (e.g., from home to hospital, between facilities, or from hospital to post-acute care).

Each Transition Alert is tied to a specific visit_id and can be associated with an episode_of_care_id, allowing you to track a patient's journey through acute and post-acute care phases comprehensively.

Why Transition Alerts Matter (Use Cases)

Transition Alerts are invaluable for organizations focused on proactive care coordination, reducing readmissions, and managing patient populations effectively.

Preventing Readmissions: Receive immediate notification when a high-risk patient is discharged from a hospital, enabling timely post-discharge follow-up and care plan activation to reduce the likelihood of readmission.
Ensuring Continuity of Care: Be alerted when a patient is admitted to an emergency department or transferred to a new facility, allowing you to proactively share relevant care plans or access recent clinical data.
Proactive Care Management: Identify critical moments in a patient's journey (e.g., hospitalizations or changes in long-term care status) to trigger outreach, support services, or care management interventions.
Value-Based Care Optimization: Utilize timely transition data to improve quality metrics, ensure appropriate follow-up, and track patient movement across the continuum of care.

To receive Transition Alerts, you must subscribe your patients to MONITORING with the transition_alerts event scope using the Subscriptions API.

Signal Workflow: Using Transition Alerts

Step 1: Register the Patient

Before you can receive any Signal alerts, each patient must be registered with Particle Health. This establishes a unique particle_patient_id for the individual, which is essential for all subsequent actions.

For detailed instructions on patient registration, including API endpoints and example payloads, please refer to the Patient Registration section in Setting Up Signal.

Step 2: Subscribe to Monitoring

Once the patient is registered, you need to subscribe them to Signal's monitoring service. Your project will have Transition Alerts enabled as a feature by your Particle Health Administrator. This setup only needs to be done once per patient or project.

Example Subscription Payload:
```
{
  "particle_patient_id": "c361d528eab1f611967ff6c62351cb1c",
  "type": ["MONITORING"]
}
```
For full details on patient subscription methods and API calls, refer to the Patient Subscription section in Setting Up Signal.

Step 3: Receive Webhook Notifications

When a transition event (e.g., an admission, discharge, or transfer) is detected for a subscribed patient, Particle will send a webhook notification to your registered callback endpoint. This notification uses a CloudEvents structure and is PHI-free, serving as a signal to retrieve the full, detailed data.

For information on how to develop, host, and register your webhook endpoint, please see the Configure Your Callback Endpoint section in Setting Up Signal.

Webhook Type: com.particlehealth.api.v2.transitionalerts

Example Webhook Payload (Discharge Alert):

{
  "specversion": "1.0",
  "type": "com.particlehealth.api.v2.transitionalerts",
  "subject": "Hospital Discharge", // Discharge Summary Available, Visit End Time Updated
  "source": "api/notifications",
  "id": "1a2b3c4d-5e6f-7g8h-9i10-jk11lm12n13o",
  "time": "2025-06-18T14:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "particle_patient_id": "9c6d9cf3-15c2-4b65-b8e3-836ef6cf2f13",
    "event_type": "Discharge", // Possible values: Admission, Discharge, Transfer, etc.
    "event_sequence": 2,
    "is_final_event": true,
    "resources": [
      {
        "file_id": "d6a96f73-eb18-4faa-b021-143e7777fe8b",
        "resource_ids": [
          "transitions/c4e9b1f0-0c2f-4a3e-a3a7-1139fd254d29",
          "episodes_of_care/b24e3f8d-94b2-4df3-8fbd-f6a5f8b3610a"
        ]
      }
    ]
  }
}

Key Fields in data payload:
- particle_patient_id: The unique identifier for the patient.
- event_type: The specific type of transition (e.g., Admission, Discharge, Transfer).
- event_sequence: Indicates the order of events within an episode of care.
- is_final_event: A boolean indicating if this is the final event in an episode of care (e.g., final discharge).
- resources: Contains file_id (for file-based retrieval) and resource_ids (which include the transitions/{transition_id} and episodes_of_care/{episode_of_care_id} needed for data retrieval via the Particle API).

Step 4: Retrieve Data

Upon receiving a Transition Alert webhook, you can retrieve the full, detailed, and PHI-containing transition and episode data as FLAT datasets using the Particle API.

You can retrieve the structured data referenced in the alert using one of the following methods:

Option A: Retrieve All Datasets Related to a Specific Transition (by `transition_id`)

This method returns all relevant records across datasets (e.g., transitions, encounters, medications, problems, etc.) associated with the transition_id referenced in the webhook's resources array (transitions/{transition_id}).

Request:

GET /patients/{particle_patient_id}/flat?transition_id={transition_id}

Example:

GET /patients/9c6d9cf3-15c2-4b65-b8e3-836ef6cf2f13/flat?transition_id=c4e9b1f0-0c2f-4a3e-a3a7-1139fd254d29

Option B: Retrieve Only the Transition Dataset for that event (by `resource_type` and `transition_id`)

To retrieve only the core transition record(s) for a specific visit, use the resource_type=TRANSITIONS parameter along with the transition_id.

Request:

GET /patients/{particle_patient_id}/flat?resource_type=TRANSITIONS&transition_id={transition_id}

Example:

GET /patients/9c6d9cf3-15c2-4b65-b8e3-836ef6cf2f13/flat?resource_type=TRANSITIONS&transition_id=c4e9b1f0-0c2f-4a3e-a3a7-1139fd254d29

Option C: File-Based Retrieval (by `file_id`)

If the webhook payload includes a file_id in the resources array, you can use it for direct file-based retrieval.

Request:GET /patients/{particle_patient_id}/ccda/{file_id}

Example:

GET /patients/{particle_patient_id}/ccda/d6a96f73-eb18-4faa-b021-143e7777fe8b

Handling Discharge Summaries with Transition Alerts

Discharge summaries are closely integrated with Transition Alerts:

Bundled with Transition Data: The transition dataset retrieved via the Flat API will include a discharge_summary field (e.g., "discharge_summary": "document_reference/abc123"). This field references the associated discharge summary document.
Retrieving the Summary Document: You can then retrieve the discharge summary document itself using its document_reference/{id} via the Particle API:

GET /patients/{particle_patient_id}/flat?resource_ids=document_reference/abc123
- Later Availability: If the discharge summary is not immediately available when the initial Transition Alert is sent, a second Transition Alert webhook (with the same transition_id) will be sent when the summary becomes available. The updated transition record retrieved via the API will then include a populated discharge_summary field.

What triggers a transition alert?

We send a transition alert any time we detect that a subscribed patient experiences a significant care event at a hospital or similar facility. Alerts help you act quickly by notifying you when your patients move through key transitions of care.

We currently send alerts for the following events:

Admission

We send an alert when the patient is admitted to a facility for care, such as an inpatient hospital stay, skilled nursing facility (SNF), emergency room (ER), or observation stay.

Example webhook payload:

{
  "specversion": "1.0",
  "type": "com.particlehealth.api.v2.transitionalerts",
  "subject": "Hospital Admission",
  "source": "api/notifications",
  "id": "c6d3e4f5-6789-1234-5678-90abcdef1234",
  "time": "2025-07-01T14:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "particle_patient_id": "9c6d9cf3-15c2-4b65-b8e3-836ef6cf2f13",
    "event_type": "Admission",
    "event_sequence": 1,
    "is_final_event": false,
    "resources": [...]
  }
}

Discharge

We send an alert when the patient is discharged, meaning they're released from care and sent home, transferred to another facility, or otherwise officially no longer under care.

Example webhook payload:

{
  "specversion": "1.0",
  "type": "com.particlehealth.api.v2.transitionalerts",
  "subject": "Hospital Discharge", //Discharge Summary Available
  "source": "api/notifications",
  "id": "1a2b3c4d-5e6f-7g8h-9i10-jk11lm12n13o",
  "time": "2025-06-18T14:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "particle_patient_id": "9c6d9cf3-15c2-4b65-b8e3-836ef6cf2f13",
    "event_type": "Discharge",
    "event_sequence": 2,
    "is_final_event": true,
    "resources": [...]
  }
}

📝 Note on discharge summaries:

Sometimes a discharge summary document is not yet available when the initial discharge alert is sent. When the summary becomes available later, we'll send another Discharge alert for the same visit with the subject listed as Discharge Summary Available. You can then retrieve the updated data, which will now include the discharge summary reference.

Transfer

We send an alert when the patient is transferred within the facility, moving from one level of care, unit, or location to another without being discharged.

Example webhook payload:

{
  "specversion": "1.0",
  "type": "com.particlehealth.api.v2.transitionalerts",
  "subject": "Hospital Transfer",
  "source": "api/notifications",
  "id": "abc12345-def6-7890-ab12-cd34ef56gh78",
  "time": "2025-07-02T09:45:00Z",
  "datacontenttype": "application/json",
  "data": {
    "particle_patient_id": "9c6d9cf3-15c2-4b65-b8e3-836ef6cf2f13",
    "event_type": "Transfer",
    "event_sequence": 3,
    "is_final_event": false,
    "resources": [...]
  }
}

⚰️ Death

We send an alert when the patient's record indicates they passed away during their care episode.

Example webhook payload:

{
  "specversion": "1.0",
  "type": "com.particlehealth.api.v2.transitionalerts",
  "subject": "Patient Death",
  "source": "api/notifications",
  "id": "7890abcd-1234-ef56-7890-gh12ij34kl56",
  "time": "2025-07-03T02:15:00Z",
  "datacontenttype": "application/json",
  "data": {
    "particle_patient_id": "9c6d9cf3-15c2-4b65-b8e3-836ef6cf2f13",
    "event_type": "Death",
    "event_sequence": 4,
    "is_final_event": true,
    "resources": [...]
  }
}

What is a Transition Alert?

Why Transition Alerts Matter (Use Cases)

Signal Workflow: Using Transition Alerts

Step 1: Register the Patient

Step 2: Subscribe to Monitoring

Step 3: Receive Webhook Notifications

Step 4: Retrieve Data

Option A: Retrieve All Datasets Related to a Specific Transition (by transition_id)

Option B: Retrieve Only the Transition Dataset for that event (by resource_type and transition_id)

Option C: File-Based Retrieval (by file_id)

Handling Discharge Summaries with Transition Alerts

What triggers a transition alert?

Admission

Discharge

Transfer

⚰️ Death

Option A: Retrieve All Datasets Related to a Specific Transition (by `transition_id`)

Option B: Retrieve Only the Transition Dataset for that event (by `resource_type` and `transition_id`)

Option C: File-Based Retrieval (by `file_id`)