Overview

To set up and test Signal workflows in Sandbox, you will need to follow the same steps required to configure Signal in production. The one key difference is that you will need to trigger a query and a Signal Alert webhook notifications to your callback endpoint in Sandbox, in order to simulate the experience of receiving an alert in production. These will not be required in the production workflow. You can find more information on setting up Signal here.

We have established a suite of Postman collections that enable you to configure and test Signal workflows in our Sandbox environment.

As in Production, in order to set up and test Signal in Sandbox, you will first need to create patients and subscriptions for your patients in Sandbox, via the following steps:

1. Authenticate

Generate a JSON web token using Authentication.

2. Register a Sandbox Test Patient

Use the [POST /api/v2/patients]() endpoint to create a patient.
All Sandbox alerts require one of the following synthetic patients. Only the highlighted patients contain Transition Alert data.

Sample Request

{
    "address_city": "Brooklyn",
    "address_lines": [
        "999 Dev Drive"
    ],
    "address_state": "NY",
    "date_of_birth": "1954-12-01",
    "email": "[email protected]",
    "family_name": "Quark-Nucleus",
    "gender": "Female",
    "given_name": "Kam",
    "npi": "1234",
    "postal_code": "11111",
    "purpose_of_use": "TREATMENT",
    "ssn": "123-45-6789",
    "telephone": "1-234-567-8910",
    "patient_id": "test-kam-quark" --this needs to be unique for each patient
}

Sample Response

{
    "given_name": "Kam",
    "family_name": "Quark-Nucleus",
    "date_of_birth": "1954-12-01",
    "gender": "FEMALE",
    "ssn": "123-45-6789",
    "email": "[email protected]",
    "address_lines": [
        "999 Dev Drive"
    ],
    "address_state": "NY",
    "address_city": "Brooklyn",
    "postal_code": "11111",
    "telephone": "(234) 567-8910",
    "patient_id": "test-kam-quark",
    "particle_patient_id": "d939196d-0c80-4e82-b0e1-19f9ee271085",
    "consent": null
}

📘

Make sure you store the particle_patient_id, you will need it for future calls in this workflow.

3. Subscribe patients to Signal monitoring - Optional

NOTE this step is only necessary if you want to specify a subset of patients to monitor. If you want to monitor ALL of your patients, you can reach out to your Particle representative to automatically enable Signal for all patients for your organization.

Subscribe your patient(s) to Signal notifications via the Subscriptions API.

Sample Request for Individual Patient

{
  "subscriptions": [
    {
      "type": "MONITORING",
    }
  ]
}

Sample Response

{
  "subscriptions": [
    {
      "id": "39774a2f-b6fb-46a0-88c9-30843a5127b7",
      "type": "MONITORING",
    }
  ]
}

4. (Sandbox-Only) Create a Query

⚠️

In production, Signal automatically generates queries for subscribed patients. In Sandbox, you must create a query manually to simulate network activity.

Using the particle_patient_id you received in step 2, trigger a query for the patient using POST /api/v2/queries

See Create Query API.

5. (Sandbox-Only) Trigger an Alert

⚠️

In production, Particle will automatically push a webhook notification to you to alert you that there is new data available. In Sandbox, you must use an API call to simulate the webhook triggering.

After queries have completed from step 4 (~2–5 minutes), simulate an alert:
[POST /api/v1/patients/{particle_patient_id}/subscriptions/trigger-sandbox-workflow](https://docs.particlehealth.com/v1.6/reference/post_api-v1-patients-particle-patient-id-subscriptions-trigger-sandbox-workflow-1#/)

_You will need to make sure you have a valid callback URL set up to receive webhooks. _

➡️

Note: Unlike in the production environment, we do not need to pre-register the callback URL for our customers in order for them to start receiving notifications. You are free to use any callback URL you would like.

Valid workflow values:

Example Admit Alert:

{ 
 "workflow": "ADMIT\_TRANSITION\_ALERT",
 "callback\_url": "https\://your-webhook-receiver",
 "display\_name": "Test Admit Alert"
}

_Example Admit Alert Webhoo_k

{
  "specversion": "1.0",
  "type": "com.particlehealth.api.v2.transitionalerts",
  "subject": "Hospital Admit", // 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": "d939196d-0c80-4e82-b0e1-19f9ee271085",
    "event_type": "Admission", // 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",
        ]
      }
    ]
  }
}

6. Retrieve the Data

Using the Data Retrieval APIs you can retrieve the data related that alert.

For example, using GET api/v2/patients/{particle_patient_id}/flat you can retrieve all of the data in the flat format for that patient. If you are specifically looking for a resource, like the Transitions table, you can use GET api/v2/patients/{particle_patient_id}/flat?TRANSITIONSto return just the transitions table for that patient.

If you want to pull the files related to the alert, you can use GET api/v2/patients/{particle_patient_id}/ccda?{file_id}.

Reference Details for Special Alert Types

Referral Alerts

If you are looking to test out receiving Referral Alerts for Referral Management, you will also need to register the Referral Organization supported in Sandbox, to be able to configure monitoring for patient referrals to the organization. See details on test organizations below.

POST /api/v1/referrals/organizations/registered\

Sample Request

{  
    "organizations": [  
        {  
            "oid": "2.16.840.1.113883.3.8391.5.710576"  
        }  
    ]  
}

Valid Sandbox Organizations

There is one Referral Organization currently supported in Sandbox. You will need to register this Referral Organization in order to trigger and receive Referral Alerts:

See guide for more details on how to configure Referral Management.

Sample - Referral Alert Notification

{
  "specversion": "1.0",
  "type": "com.particlehealth.api.v2.referralalert",
  "subject": "Referral Complete",
  "source": "api/notifications",
  "id": "ea77d12d-bb97-438e-82eb-1b0d10a7e3ee",
  "time": "2024-07-22T10:10:10Z",
  "datacontenttype": "application/json",
	"data": {
    "network_organization": {
      "name": "Rochester Hospital",
      "oid": "2.16.840.1.113883.3.8391.5.710576"
    },
    "particle_patient_id": "d939196d-0c80-4e82-b0e1-19f9ee271085",
    "network_alert_ids": [
	    "1cac1ea7-f3a9-43b3-bca3-04d3ec4362c5",
    ],
    "adt_message_ids": [
	    "6e7303bd-2c1a-49f2-add0-820babbdb95a",
    ],
    "referral_id": "a17846c4-4270-427b-b191-bd5e76cf8f30",
    "referral_status": "COMPLETE",
    "resources": [
      {
	      "file_id": "d6a96f73-eb18-4faa-b021-143e7777fe8b",
        "resource_ids": [
          "Encounter/b10fe2ef-47f9-4507-97c8-1a8c2215478e"
        ]
      }
    ]
  }
}

ADTs

1. After you have subscribed to test notifications and configured the appropriate call back URLs, request an ADT notification using the Register HL7v2 API.

POST /api/v1/patients/{particle_patient_id}/subscriptions/trigger-sandbox-workflow

Request Body:

{
    "workflow": "ADT", // valid: ADT
    "event_type": "A01", // valid: A01, A02, A03, A04, A08
    "callback_url": "http://test-webhook-url",// callback url to receive the test notif
    "display_name": "Test ADT Notification 1" // display name for the webhook
}

2. You will receive a notification at the callback URL you specified. This notification will contain the Patient ID and a message ID.
3. Retrieve the sample ADT message using the HL7v2 API.
   GET /hl7v2/{message_id}

Sample ADT messages are customized based on the patient and ADT event type specified.