--- title: Receiving XDR Messages from Surescripts slug: xdr/guide/receiving-xdr-messages-from-surescripts docTags: createdAt: 2026-07-30T21:09:39.065Z --- This section describes how a customer's XDR interface receives an XDR-based message delivered from Surescripts. Sending and receiving are documented independently; a customer that only receives messages can implement from this section without implementing [Sending XDR Messages to Surescripts](docId\:xZ0MTs_W6FVT5WxkvD-Q0). ## Receiving Flow Overview Receiving an XDR-based message occurs when a customer's XDR interface accepts a message delivered from Surescripts. In this direction, Surescripts is the Document Source and the customer's XDR interface is the Document Recipient (see [Roles and Architecture](docId\:daGa7Uw8ataRiYlZ3RtU9)). Surescripts delivers the message over the mutual TLS connection described in [Connectivity and Mutual TLS (mTLS)](docId\:jfGzRl2J_PROSTtsoVZa5), and the customer's system returns a synchronous response (see [Sending the Message Response](docId\:XyQrOSGPZ8458uzH0p8sU)). Customers should publish and maintain their Direct addresses in the Surescripts Directory. **Directory-based addressing is the expected and strongly recommended routing model** for Surescripts Direct messaging: Surescripts matches the recipient Direct address to a registered provider or organization record, which identifies the customer interface for delivery. Publishing addresses to the Directory is what makes recipients reliably discoverable and routable across the network, and Surescripts expects customers to publish and keep their addresses current. Domain-based routing - routing on the recipient's Direct domain rather than on an individually registered address - is technically supported and can be enabled per domain. It is **not** recommended: it reduces recipient discoverability and tends to produce stale or unpublished addresses and other data-quality and operational issues over time. Use domain-based routing only when specific addresses genuinely cannot be published in the Directory, and publish addresses to the Directory wherever possible even where domain-based routing is enabled. For address publication, endpoint configuration, participant onboarding, and routing configuration, refer to the Surescripts Directory Implementation Guide. ## Message Structure Surescripts conforms to Section 6.1 of the *XDR and XDM for Direct Secure Messaging Specification*, Version 2.1, for the SOAP headers used in Direct Secure Messaging. An incoming message contains the following: | Element | Contains | | ---------------------------------- | ------------------------------------------------------------------------------------------- | | direct\:addressBlock (SOAP header) | One direct\:from element (the sender) and one or more direct\:to elements (the recipients). | | XDS metadata authorPerson | Sender information. | | intendedRecipient | Recipient address or addresses. | A received message carries the same XDS metadata structure shown in the [Complete Referral Example](docId\:xZ0MTs_W6FVT5WxkvD-Q0) - a submission set and one or more document entries, each with their classifications and identifiers. The elements above are those most relevant when consuming a message. For a complete received message as delivered to a receiving endpoint, see [Consolidated Message Examples](docId:4pSAzF9OZZ3BbPh9NMOB7). **Multiple recipients.** Surescripts splits a message addressed to multiple recipients by receiving system. An XDR receiving system receives a message addressed to the recipient(s) it hosts; recipients served by other systems are delivered separately and are generally not listed on the message your system receives. When more than one recipient is hosted by the same receiving system, those recipients appear together as multiple direct\:to elements in the single message delivered to that system, as shown below. Each split is handled independently: the responses and Delivery Status Notifications for one receiving system are not shared with another. ### Illustrative Incoming Address Block: Two Recipients Hosted by the Same Receiving System :::CodeblockTabs Example ```xml dr.smith@direct.example-clinic.com intake@direct.example-hospital.com records@direct.example-hospital.com ``` ::: **Note:** This example is illustrative and shows two recipients hosted by the same receiving system. Recipients served by other systems are delivered as separate messages and would not appear here. ## Patient Identification Surescripts forms the outbound XDR message using information available from the inbound Clinical Direct message after normalizing and processing it for routing. Because messages can originate through different entry points and formats, the patient identification available in XDR metadata can vary. When the originating system supplies complete XDR or XDM metadata, that metadata is the most reliable source for patient identifiers and demographics in the outbound XDR message. When it does not, some patient information may be present only within clinical attachments (such as C-CDA XML or HTML, HL7 v2 content, or PDFs), or may not be available in structured metadata at all. Receiving systems should not rely on XDR metadata alone for patient matching. Determine whether your workflows need to inspect the attachment types you expect to receive for additional demographics or identifiers, and provide review handling when patient data is missing, incomplete, or ambiguous. :::hint{type="info"} **Note:** Because patient identifiers are passed unchanged from external parties, the receiving system must not rely on the identifier alone to match the clinical information to a patient record. See [XDR-Based Messaging Best Practices](docId\:zA3pMlbsxejAs5vduvf55) for patient-matching best practices, including verifying matches and allowing users to correct mismatches. ::: ## Sending the Message Response When the customer's XDR interface receives a message, it must return a synchronous Provide and Register Document Set-b Response: If the system can accept the message for delivery, it returns a Success response. If the system cannot accept the message, it returns a Failure response containing a RegistryErrorList element within the RegistryResponse element. To interoperate with the Surescripts network, the customer must implement, at a minimum, the same XDR extensions that Surescripts implements from the *XDR and XDM for Direct Secure Messaging Specification*, Version 2.1. This includes the Direct address block and the Minimal Metadata specification. Surescripts also accepts Full XDS Metadata. :::hint{type="info"} **Note:** See [XDR-Based Messaging Best Practices](docId\:zA3pMlbsxejAs5vduvf55) for best practices on handling temporary connectivity failures, queuing, and retries. ::: ## No Delivery Notification Tracking When the receiving system is not configured to send delivery notifications, Surescripts translates the synchronous responses into delivery status as follows: If the message was received and delivered to the recipient, the Success response is treated as a DSN Success. If the message was not successfully delivered, the Failure response is treated as a DSN Failure. The message is then identified with its final status, and no further responses are expected. ## DSN Examples A Delivery Status Notification (DSN) confirms whether a message was delivered successfully or failed. It is sent asynchronously, after the synchronous response, as a separate ProvideAndRegisterDocumentSet-b transaction in the reverse direction (from the receiving side back toward the original sender). The disposition (success or failure) is Base64-encoded in the Document element, and the direct\:notification element in the address block links the DSN to the original message. The examples below show the notification header, the success and failure disposition bodies, a complete DSN message, the sender's acknowledgement of the DSN, and where each part is located. :::hint{type="info"} **Note:** The direct\:notification element in the address block links a DSN to its original message. Whether a sender receives DSNs is governed by the sender's delivery notification configuration. Base64-decode the Document content to read the disposition. ::: ### Notification Header :::CodeblockTabs Direct\:notification in the address block, linking the DSN to the original message ```xml intake@direct.example-hospital.com dr.smith@direct.example-clinic.com ``` ::: ### Success Disposition :::CodeblockTabs DSN success disposition (before Base64 encoding) ```xml intake@direct.example-hospital.com success ``` ::: ### Failure Disposition :::CodeblockTabs DSN failure disposition with a reason (before Base64 encoding) ```xml intake@direct.example-hospital.com failure Mailbox not found. ``` ::: The direct\:reasonForFailure element should contain a specific, actionable description. Examples of useful reason text include: - Mailbox not found. - Message exceeds the recipient's maximum size limit. - Unsupported attachment type. - Recipient system unavailable - delivery timed out. ### Full DSN Message A DSN is delivered as a complete ProvideAndRegisterDocumentSet-b transaction. The a\:RelatesTo header and the direct\:notification element both carry the original message's MessageID, and the Document holds the Base64-encoded disposition. A complete success DSN is shown in [Consolidated Message Examples](docId:4pSAzF9OZZ3BbPh9NMOB7), ### DSN Acknowledgement Because the DSN is itself a ProvideAndRegisterDocumentSet-b transaction, the system that receives it (the original sender) returns a synchronous RegistryResponse to acknowledge it, closing the workflow. The a\:RelatesTo header carries the DSN's MessageID. :::CodeblockTabs Acknowledgement of the DSN (synchronous response) ```xml urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-bResponse urn:uuid:2c8b0e13-9f1a-4b6e-8b5a-6d7e8f901234 ``` ::: ### DSN Locations in the Message File | **Part** | **Location in the message** | | ------------------------------ | ------------------------------------------------------------------------------------- | | Notification header | Envelope -> Header -> direct\:addressBlock -> direct\:notification | | Success or failure disposition | Envelope -> Body -> ProvideAndRegisterDocumentSetRequest -> Document (Base64-encoded) | :::hint{type="info"} **Note:** An error description should be included in the direct\:reasonForFailure element of the failure disposition. :::