Receive Message
For detailed technical specifications, please refer to the Swagger documentation.
When you receive a notification of type NewMessage, the relatedMessageId field gives you the id of the message to retrieve and process. The steps below outline the recommended workflow from notification to completed handling.
The high-level flow, including how this fits into your notification consumption strategy, is described on the Overall Flow page.
1. (Optional) Fetch Message Metadata
GET /messages/{id}
Returns metadata about the message (sender, receiver, content type, business document type, etc.) without downloading the payload. Useful if you need to inspect the message before deciding whether to download it, or to enrich your local storage with routing information.
2. Download the Business Document
GET /messages/{id}/business-document
Returns the raw business document payload (XML). This is the clinical document to be processed by your application.
3. Persist the Payload Locally
Store the downloaded business document in your application's database or file storage. This ensures you have a durable copy before acknowledging the download to the server.
4. Mark the Message as Downloaded
PUT /messages/{id}/downloaded
Signals to the server that you have safely stored the message. This triggers the business document payload to be deleted from the EDI 2.0 server. After this call, the payload is no longer available via the API.
5. Process the Message in Your Application
Handle the business document according to your application's domain logic (parse, validate, route to the appropriate clinical workflow, etc.).
6. (Optional) Send an Application Receipt
After processing, you may send an application receipt (AppRec) back to the sender to confirm that the message was accepted or rejected at the application level.
You have two options:
| Option | Endpoint | Use case |
|---|---|---|
| Let the API generate the AppRec | POST /messages/{id}/apprec |
Standard case. The API produces a well-formed AppRec XML based on the information you provide. |
| Upload a custom AppRec | POST /messages |
You need to construct and upload your own AppRec XML as a regular message. |
See the Send Application Receipt page for details on both options.
7. (If Using Unread Notifications) Delete the Notification
If you are using the /notifications/unread endpoints (see the Notifications page for the two consumption flows), delete the notification once you have completed the workflow above:
POST /notifications/delete
This removes the notification from your unread queue so it does not re-appear on the next poll or stream connection.