When a monitored patient has an ADT event at a facility in the Particle community, an ADT notification will be sent to the registered callback endpoint. Refer to the Event Notifications documentation on how to set up callback endpoints to receive ADT notifications. The notification message will contain a message id and the id of the patient for whom an ADT is available. The corresponding ADT HL7v2 message can be retrieved using Particle Health HL7v2 API.

ADT Notification

{
  "specversion":"1.0",
  "id":"6a537bf6-ebc4-402e-ad27-92b3ce467dbc",
  "source":"api/notifications",
  "type":"com.particlehealth.api.v1.hl7v2",
  "datacontenttype":"application/json",
  "time":"2022-10-01T10:10:44.00Z",
  "data":{
    "patient_id":"bb97b572-17da-4e97-a306-c0daaf3328b1",
    "message_id":"2a416e07-0b8a-48dd-a327-7d6578550c04",
  }
}

Retrieving ADT HL7v2 Messages

PATH	/hl7v2/{message_id}
METHOD	GET

Example Request

curl -X POST -H “Authorization: $authToken” https://api.particlehealth.com/hl7v2/{message_id}

Response Model

eyJobDdNZXNzYWdlIjoiTVNIfF5+XFwmfFBhcnRpY2xlIEhlYWx0aF9BRFR8MTEyMl5TdC4gTWFyeSBIb3NwaXRhbF5IT1N8UkVDRUlWSU5HX0FQUHwxMjM0XlNhbXBsZSBIZWFsdGh8MjAxOTAzMDYwODE5NDl8fEFEVF5BMDh8NzUyZjNlYWItMmQxMS00MTFhLWI1OTctMmIwODMyNWQxZjIwfFB8Mi41XHJFVk58QTA4fDIwMTkwMzA1MjE0MzAwfHxFRElUX0VOQ09VTlRFUlxyUElEfDF8MzU3NzQ0MTBeXl5QUF5QUHxhNTc4MmEwNi05NWI1LTQ3YjMtYmUxOS0xMGVhNjA2OTNmM2NeXl5zYW1ec2FtfHxXZWFzbGV5XkZyZWRefHwxOTc4MDQwMXxNfHx8MTE0MDAgTGFuc2Rvd25lIFN0Xl5Cb3N0b25eTUFeMDIyMTV8fHx8fHx8NDM5NjgyMzg5MDY0fFxyUEQxfHx8fDEwNjM0ODQwNTNeSGFxdWVeTW9oYW1tZWReXl5eXHJQVjF8MXxFfHx8fHwxNjAxMjM0NTY3XlJ1YmV1c15IYWdyaWReXl5efHx8fHx8fEhvbWV8fHx8fDQ1NDEyMzQ1Njc4OXx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHwyMDE5MDMwNTIxNDMwMHx8fHx8fDMxMzc3NTczXHJJTjF8MXx8fFNlbGYgUGF5ICBKfHx8fHx8fHx8fHxTZWxmIFBheXx8fHx8fHx8fHx8fHx8fHx8fHx8fFVOS05PV05cclpNRHw1MTYwM2M2NS04MzliLTQ4YTAtOWU5Zi1iM2I3ZmEwYzEzZDBcclpQUHxQUk9HUkFNU1xyWlBQfC0tLS0tLS0tXHJaUFB8MS4gU2FtcGxlIEhlYWx0aFxyWlBQfDIuIEFDTUUgSGVhbHRoXHJaUFB8XHJaUFB8XHJaUFB8UFJBQ1RJQ0VTXHJaUFB8LS0tLS0tLS1cclpQUHwxLiBQcmFjdGljZSBVbmtub3duXHJaUFB8XHJaUFB8XHJaUFB8Q0FSRSBDT09SRElOQVRPUlNcclpQUHwtLS0tLS0tLS0tLS0tLS0tLVxyWlBQfE5hbWUuICAgOiBUcmFuc2l0aW9ucyBvZiBDYXJlIFRlYW1cclpQUHxQaG9uZS4gIDogODU1LTY3Ny04Nzg3XHJaUFB8RW1haWwuICA6IFxyWlBQfEZheC4gICAgOiA4NjYtNTY3LTEwMTBcclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tXHJaUFB8TmFtZS4gICA6IFV0aWxpemF0aW9uIE1hbmFnZW1lbnRcclpQUHxQaG9uZS4gIDogODc3LTMzMy02MTYxXHJaUFB8RW1haWwuICA6IFxyWlBQfEZheC4gICAgOiBcclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tXHJaUFB8XHJaUFB8XHJaUFB8QURNSVQgQ0FSRSBJTlNUUlVDVElPTlNcclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLVxyWlBQfDEuIEFsbCBvdGhlciBoZWFsdGggcGxhbnMgY2FsbCAoMjEyKSA1NTUtODY5NyBhbmQgYXNrIHRvIHNwZWFrIHdpdGggdGhlIEV4dGVuc2l2aXN0IG9uIGNhbGwuXHJaUFB8Mi4gRmlkZWxpcyBNTVAgY2FsbCAoODc3KSAzMzMtNjE2MSBmb3IgYW4gYXV0aG9yaXphdGlvbi5cclpQUHxcclpQUHxcclpQUHxESVNDSEFSR0UgQ0FSRSBJTlNUUlVDVElPTlNcclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS1cclpQUHwxLiBDYWxsICg4NTUpIDI1NS04MjgyIHRvIHJlYWNoIG9yIGdldCBhIG1lc3NhZ2UgdG8gYSBUcmFuc2l0aW9uIENvb3JkaW5hdG9yLlxyWlBQfFxyWlBQfFxyWlBQfE9USEVSIENBUkUgUFJPVklERVJTXHJaUFB8LS0tLS0tLS0tLS0tLS0tLS0tLS1cclpQUHxOYW1lLiAgIDogTHVuYSBMb3ZlZ29vZCBcclpQUHxQaG9uZS4gIDogXHJaUFB8RW1haWwuICA6IFxyWlBQfEZheC4gICAgOiBcclpQUHxDb2hvcnQgTmFtZSAgICA6IFByYWN0aWNlIFVua25vd25cclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tXHJaUFB8XHJaUFB8XHIifQ==

Message Format

ADT HL7v2 messages are retrieved by calling the HL7v2 API with the message_id, which is included in the ADT Notification sent to the registered callback endpoint. The HL7 message is embedded inside a JSON structure which is encoded in Base64.

Here is a sample base64 encoded HL7v2 API response:

eyJobDdNZXNzYWdlIjoiTVNIfF5+XFwmfFBhcnRpY2xlIEhlYWx0aF9BRFR8MTEyMl5TdC4gTWFyeSBIb3NwaXRhbF5IT1N8UkVDRUlWSU5HX0FQUHwxMjM0XlNhbXBsZSBIZWFsdGh8MjAxOTAzMDYwODE5NDl8fEFEVF5BMDh8NzUyZjNlYWItMmQxMS00MTFhLWI1OTctMmIwODMyNWQxZjIwfFB8Mi41XHJFVk58QTA4fDIwMTkwMzA1MjE0MzAwfHxFRElUX0VOQ09VTlRFUlxyUElEfDF8MzU3NzQ0MTBeXl5QUF5QUHxhNTc4MmEwNi05NWI1LTQ3YjMtYmUxOS0xMGVhNjA2OTNmM2NeXl5zYW1ec2FtfHxXZWFzbGV5XkZyZWRefHwxOTc4MDQwMXxNfHx8MTE0MDAgTGFuc2Rvd25lIFN0Xl5Cb3N0b25eTUFeMDIyMTV8fHx8fHx8NDM5NjgyMzg5MDY0fFxyUEQxfHx8fDEwNjM0ODQwNTNeSGFxdWVeTW9oYW1tZWReXl5eXHJQVjF8MXxFfHx8fHwxNjAxMjM0NTY3XlJ1YmV1c15IYWdyaWReXl5efHx8fHx8fEhvbWV8fHx8fDQ1NDEyMzQ1Njc4OXx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHwyMDE5MDMwNTIxNDMwMHx8fHx8fDMxMzc3NTczXHJJTjF8MXx8fFNlbGYgUGF5ICBKfHx8fHx8fHx8fHxTZWxmIFBheXx8fHx8fHx8fHx8fHx8fHx8fHx8fFVOS05PV05cclpNRHw1MTYwM2M2NS04MzliLTQ4YTAtOWU5Zi1iM2I3ZmEwYzEzZDBcclpQUHxQUk9HUkFNU1xyWlBQfC0tLS0tLS0tXHJaUFB8MS4gU2FtcGxlIEhlYWx0aFxyWlBQfDIuIEFDTUUgSGVhbHRoXHJaUFB8XHJaUFB8XHJaUFB8UFJBQ1RJQ0VTXHJaUFB8LS0tLS0tLS1cclpQUHwxLiBQcmFjdGljZSBVbmtub3duXHJaUFB8XHJaUFB8XHJaUFB8Q0FSRSBDT09SRElOQVRPUlNcclpQUHwtLS0tLS0tLS0tLS0tLS0tLVxyWlBQfE5hbWUuICAgOiBUcmFuc2l0aW9ucyBvZiBDYXJlIFRlYW1cclpQUHxQaG9uZS4gIDogODU1LTY3Ny04Nzg3XHJaUFB8RW1haWwuICA6IFxyWlBQfEZheC4gICAgOiA4NjYtNTY3LTEwMTBcclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tXHJaUFB8TmFtZS4gICA6IFV0aWxpemF0aW9uIE1hbmFnZW1lbnRcclpQUHxQaG9uZS4gIDogODc3LTMzMy02MTYxXHJaUFB8RW1haWwuICA6IFxyWlBQfEZheC4gICAgOiBcclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tXHJaUFB8XHJaUFB8XHJaUFB8QURNSVQgQ0FSRSBJTlNUUlVDVElPTlNcclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLVxyWlBQfDEuIEFsbCBvdGhlciBoZWFsdGggcGxhbnMgY2FsbCAoMjEyKSA1NTUtODY5NyBhbmQgYXNrIHRvIHNwZWFrIHdpdGggdGhlIEV4dGVuc2l2aXN0IG9uIGNhbGwuXHJaUFB8Mi4gRmlkZWxpcyBNTVAgY2FsbCAoODc3KSAzMzMtNjE2MSBmb3IgYW4gYXV0aG9yaXphdGlvbi5cclpQUHxcclpQUHxcclpQUHxESVNDSEFSR0UgQ0FSRSBJTlNUUlVDVElPTlNcclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS1cclpQUHwxLiBDYWxsICg4NTUpIDI1NS04MjgyIHRvIHJlYWNoIG9yIGdldCBhIG1lc3NhZ2UgdG8gYSBUcmFuc2l0aW9uIENvb3JkaW5hdG9yLlxyWlBQfFxyWlBQfFxyWlBQfE9USEVSIENBUkUgUFJPVklERVJTXHJaUFB8LS0tLS0tLS0tLS0tLS0tLS0tLS1cclpQUHxOYW1lLiAgIDogTHVuYSBMb3ZlZ29vZCBcclpQUHxQaG9uZS4gIDogXHJaUFB8RW1haWwuICA6IFxyWlBQfEZheC4gICAgOiBcclpQUHxDb2hvcnQgTmFtZSAgICA6IFByYWN0aWNlIFVua25vd25cclpQUHwtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tXHJaUFB8XHJaUFB8XHIifQ==

Which corresponds to the following decoded JSON HL7v2 message:

{"hl7Message":"MSH|^~\\&|Particle Health_ADT|1122^St. Mary Hospital^HOS|RECEIVING_APP|1234^Sample Health|20190306081949||ADT^A08|752f3eab-2d11-411a-b597-2b08325d1f20|P|2.5\rEVN|A08|20190305214300||EDIT_ENCOUNTER\rPID|1|35774410^^^PP^PP|a5782a06-95b5-47b3-be19-10ea60693f3c^^^sam^sam||Weasley^Fred^||19780401|M|||11400 Lansdowne St^^Boston^MA^02215|||||||439682389064|\rPD1||||1063484053^Haque^Mohammed^^^^\rPV1|1|E|||||1601234567^Rubeus^Hagrid^^^^|||||||Home|||||454123456789|||||||||||||||||||||||||20190305214300||||||31377573\rIN1|1|||Self Pay  J|||||||||||Self Pay|||||||||||||||||||||UNKNOWN\rZMD|51603c65-839b-48a0-9e9f-b3b7fa0c13d0\rZPP|PROGRAMS\rZPP|--------\rZPP|1. Sample Health\rZPP|2. ACME Health\rZPP|\rZPP|\rZPP|PRACTICES\rZPP|--------\rZPP|1. Practice Unknown\rZPP|\rZPP|\rZPP|CARE COORDINATORS\rZPP|-----------------\rZPP|Name.   : Transitions of Care Team\rZPP|Phone.  : 855-677-8787\rZPP|Email.  : \rZPP|Fax.    : 866-567-1010\rZPP|-------------------------------------\rZPP|Name.   : Utilization Management\rZPP|Phone.  : 877-333-6161\rZPP|Email.  : \rZPP|Fax.    : \rZPP|-------------------------------------\rZPP|\rZPP|\rZPP|ADMIT CARE INSTRUCTIONS\rZPP|-----------------------\rZPP|1. All other health plans call (212) 555-8697 and ask to speak with the Extensivist on call.\rZPP|2. Fidelis MMP call (877) 333-6161 for an authorization.\rZPP|\rZPP|\rZPP|DISCHARGE CARE INSTRUCTIONS\rZPP|---------------------------\rZPP|1. Call (855) 255-8282 to reach or get a message to a Transition Coordinator.\rZPP|\rZPP|\rZPP|OTHER CARE PROVIDERS\rZPP|--------------------\rZPP|Name.   : Luna Lovegood \rZPP|Phone.  : \rZPP|Email.  : \rZPP|Fax.    : \rZPP|Cohort Name    : Practice Unknown\rZPP|-------------------------------------\rZPP|\rZPP|\r"}

Receiving Test ADT Messages in Sandbox

Configure the callback URL that you would like us to send ADT notifications to.

➡️ *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.*

Submit demographics for a patient using the Patients API.

POST /api/v1/patients
Request an ADT notification using the HL7v2 API.

POST /hl7v2/notification/test

Request Body:

{
    "patient_id": "test-patient-id",
    "event_type": "A01", // valid: A01, A02, A03, A04, A08
    "callback_url": "http://test-webhook-url", // URL of webhook from step 2
    "display_name": "Test ADT Notification 1" // display name for the webhook
}

You will receive a notification at the webhook you specified. This notification will contain the Patient ID and a message ID.
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.

Frequently Asked Questions

1. What is the format of the ADT message?

ADT messages are delivered as Base64-encoded JSON containing the raw HL7 V2 message. Messages are encoded in Base64 to ensure HL7 V2 standard encoding characters (| & ^ ~) are transmitted without corruption.

2. Do you support ADT messages in FHIR or FLAT?

At this time ADT messages are not available in the FHIR or FLAT formats. However, we are exploring offering this feature in the future, if there's sufficient demand.

3. What ADT event types are available?

The following ADT events are supported:

Message Type	Action
A01	Admit Patient
A02	Transfer Patient
A03	Discharge Patient
A04	Register Patient
A08	Update Patient
A11	Cancel Admit
A12	Cancel Transfer
A13	Cancel Discharge
A21	Start of medical leave of absence (MLOA)
A22	Return from MLOA
A52	Cancel start of MLOA
A53	Cancel return from MLOA

Note:

Update Patient (A08)

Applies to the preceding event. When patient information is updated, such as insurance, that update should link to the previous admission or discharge event.

Register Patient (A04)

Creates a presented event for ED presentations. This means for an A04 message with a patient class of emergency, the event will be mapped to CREATE_PRESENTED in the EVN.4. Additionally, Registration events do not precede an admit event unless the patient is returning to the ED.