Referral Alerts

What is a Referral Alert?

A Referral Alert informs you when a new referral document has been identified for a patient you've subscribed to Particle Signal. These alerts are specifically triggered when Particle detects clinical context from a specialist encounter at an organization that you have asked us to monitor for patient referrals. This allows you to track referrals to and from your pre-specified referral organizations across national Health Information Networks (HINs).

This alert signifies that the referral status has been updated to COMPLETE, and it provides a direct link to the associated clinical context.

Why Referral Alerts Matter (Use Cases)

Referral Alerts are essential for organizations that manage patient referrals, coordinate care with external partners, or need to track patient movement within a specific referral network.

Closed-Loop Referrals: Get notified as soon as your patient has seen the specialist, with the specialist's recommendations readily available, helping to streamline follow-up and prevent care gaps.
Care Coordination: Proactively manage patient referrals and ensure consistent, coordinated care.
Network Management: Monitor patient referrals to and from your registered organizations.
Improve MIPS Scores: Optimize reimbursement rates by ensuring timely follow-up on referrals.
Reduced Manual Effort: Eliminate manual chart chasing by receiving proactive notifications.

How Referral Alerts Work (Technical Details)

Referral Alerts are unique because they are tied to your specific list of registered referral organizations. Particle monitors for new referral documents that involve these organizations.

Triggering Criteria:

A Referral Alert is triggered when Particle Health retrieves clinical context from a specialist encounter at an organization that you have previously registered with Particle for patient referrals. When this occurs, Particle will update the referral status to COMPLETE and send a Referral Alert.

Registering Referral Organizations (Prerequisite for Referral Alerts):

To receive Referral Alerts, you must first register the Object Identifiers (OIDs) of the specific referral organizations you wish to monitor. Particle will then monitor for referral documents involving these registered organizations.

How to Register Referral Organizations: You register organizations using the Referral Organizations API. First, you can retrieve a list of all supported organizations and their OIDs by calling the GET /referrals/organizations endpoint. Once you have the OID(s) for the organizations you wish to monitor, send a POST request to the following endpoint:
- Request:POST https://api.particlehealth.com/api/v1/referrals/organizations/registered
- Example Payload:
```
{
  "organizations": [
    {
      "oid": "2.16.840.1.113883.3.8391.5.710576"
    }
  ]
}
```
- For more details on managing referral organizations, including retrieving a list of supported organizations, refer to the Referral Management API documentation.

Webhook Payload Structure:

When a Referral Alert is triggered, Particle will send a POST request to your registered callback endpoint.

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

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

Example Webhook Payload:

{
  "specversion": "1.0",
  "type": "com.particlehealth.api.v2.referral",
  "subject": "Referral Complete",
  "source": "api/notifications",
  "id": "ref789ab-12cd-34ef-5678-90gh12ij34kl",
  "time": "2025-08-01T09:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "network_organization": {
      "name": "Specialist Clinic",
      "oid": "2.16.840.1.113883.3.8391.5.ORG456"
    },
    "particle_patient_id": "d939196d-0c80-4e82-b0e1-19f9ee271085",
    "network_alert_ids": [
      "1cac1ea7-f3a9-43b3-bca3-04d3ec4362c5"
    ],
    "referral_id": "unique-referral-identifier",
    "referral_status": "COMPLETE",
    "resources": [
      {
        "file_id": "referral-doc-file-id-abc",
        "resource_ids": [
          "document_reference/referral-doc-resource-id"
        ]
      }
    ]
  }
}

Key Fields in data payload:
- network_organization: Information about the organization where the referral encounter was detected (name and OID).
- particle_patient_id: The unique identifier for the patient.
- network_alert_ids: IDs of related Network Alerts.
- referral_id: A unique identifier for the referral.
- referral_status: The status of the referral, which will be COMPLETE for this alert type.
- resources: Contains file_id (for file-based retrieval) and resource_ids (which include the document_reference/{id} needed for data retrieval via the V2 Query API).

Retrieving Associated Data:

To retrieve the full clinical context from the referral, you will use the file_id or resource_ids provided in the webhook payload with the V2 Query API.

Retrieve by resource_ids : This is the primary way to fetch the specific referral document.
```
GET /patients/{particle_patient_id}/flat?resource_type={resource}&visit_id={visit_id}
```
Retrieve by file_id : If the file_id is provided, you can retrieve the file(s) associated with that event.

GET /flat/{file_id}

Implementation Best Practices

Automated Referral Queues: Integrate these alerts to automatically populate referral management systems or work queues, prompting follow-up actions.
Network Performance Tracking: Use the network_organization data to analyze referral patterns and optimize your partner network.
Proactive Patient Engagement: Initiate outreach to patients who have new referrals to ensure they understand next steps and facilitate appointments.
Sandbox Testing: Thoroughly test your integration with Referral Alerts in the Particle Sandbox environment.