--- title: Message Definitions slug: net2net-rest/guide/message-definitions docTags: createdAt: 2026-06-12T09:48:23.848Z --- ## Message Header Surescripts uses a message header for all messages. The message header contains information required for routing of the message and is separate from the clinical content of the message body. The XML schemas are available as a supplemental file. ### Message Header – XML In XML diagrams, blocks that are solid are mandatory, whereas blocks that have dotted lines are conditional. ::Image[]{src="https://api.archbee.com/api/optimize/fNEeV2bO-J-V0NK1eH_VR/LauyjOIFqIuRonNwUESkT_message-definitions.png" position="flex-start" size="70" initialPath="../../Resources/Images/Net2Net REST v1.5/Message Definitions.png" githubPath="Content/Resources/Images/Net2Net REST v1.5/Message Definitions.png" width="348" height="328" darkWidth="348" darkHeight="328" showCaption="false"} :::hint{type="info"} **Note: **RecipientInformation is used only for guaranteed delivery. ::: ### Patient Information *Clinical* messages often relate to the care of a particular patient. Customers should include patient identification data with the message to assist the recipient's software in matching the patient to a local patient record. When sending a new message, a customer should include \ in the message, which should include, at minimum, the \, \ elements and should include the \, \, and \ elements, as well as a valid occurrence of the \ element. :::hint{type="info"} **Note: **Surescripts does not guarantee the patient identifier provided in the message is unique or specific to the recipient's organization. When receiving messages, the patient identifier should not be used exclusively to match the clinical information provided in the message with a patient within the recipient's organization. ::: A message should contain data for a single patient. If a message is not related to a single patient the sender should not specify any \ in the message. **Patient Information** ::Image[]{src="https://api.archbee.com/api/optimize/fNEeV2bO-J-V0NK1eH_VR/6TerseeInNEr9UJxoOOLA_message-definitions1.png" position="flex-start" size="90" initialPath="../../Resources/Images/Net2Net REST v1.5/Message Definitions_1.png" githubPath="Content/Resources/Images/Net2Net REST v1.5/Message Definitions_1.png" width="537" height="325" darkWidth="537" darkHeight="325" showCaption="false"} ### Message Header Elements **M/C Mandatory or Conditional** | **Element** | **Code** | **Comments** | | ------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | N2NMessage/@version | mandatory  | Message version number.
Value = CIv6 | | N2NMessage/@release | mandatory  | Message release number.
Value = 0 | | Recipients | mandatory  | List of all receivers of the message. | | To | mandatory  | The identification of the intended receiver of the message. | | To/@Qualifier | mandatory  | Value = DIRECT | | To/@CC | conditional  | Indicates that the recipient is a secondary (informational) recipient of the message.
CC = true
If not true, do not include this attribute. | | To/@FriendlyName | conditional  | Value identifies a user friendly name of the recipient used for display. | | To/@Route | conditional  | Only added by Surescripts to -indicate that the receiving system is responsible for responding for the identified recipient.
Route = true
If not true, Receiving System is not responsible for responding to the message. | | From | mandatory  | The identification of the sender of the message.
See [Multiple Recipient Messages](docId:9OD7XMMyJp74RwiSGyguf) for more information. | | From/@Qualifier | mandatory  | Valid Values:
DIRECT
ZZZ - only used when synchronously responding to a multiple recipient message | | From/@FriendlyName | conditional  | Value identifies a user friendly name of the sender used for display. | | MessageID | mandatory  | The sender should ensure the combination of the From and MessageID elements is unique for at least 18 months. Surescripts recommends an unformatted Globally Unique Identifier (GUID). | | RelatesToMessageID | conditional  | On a responding message, this field is mandatory for the Error, Status, and Verify messages, and is used to link the original message to the response. | | SentTime | mandatory  | Date of the transmission. Please see [UTC Time Format](docId\:UhijxbZQnOG_8WuGh-KB3) section. | | SenderSoftware | mandatory  | Identifies the entity responsible that generated the message. Contains the software vendor name, product, and version/release. | | SenderSoftwareDeveloper | mandatory  | Identifies the entity responsible for the software that generated the message. The developer may be a software vendor or, if the software was developed "in-house", the developer is the entity actually sending the message (e.g., a chain). The value transmitted is determined by the Sender Software Developer. | | SenderSoftwareProduct | mandatory  | The text field that identifies the software developer’s product, as determined by the software developer. | |   SenderSoftwareVersionRelease | mandatory  | The text field that identifies the version and release of the software product, as determined by the software developer. | | TestMessage | conditional  | Do not include this element in production messages. | | RecipientInformation | mandatory  | Used for Guaranteed Delivery only. | | PatientInformation | conditional  | Contains demographic information on the patient that is associated with the clinical message. | | Given | conditional  | Patient’s given (first name) | | Middle | conditional  | Patient’s middle names(s) | | Family | conditional  | Patient’s family (last name) | | Suffix | conditional  | Patient’s name suffix | | DOB | conditional  | Patient's Date of Birth in format YYYY-MM-DD where YYYY indicates the year: MM indicates the month and DD indicates the day. | | Gender | conditional  | Patient’s Administrative gender code.
Valid Values:
F = FemaleM = MaleO = OtherU = Unknown | | Zip | conditional  | Patient’s zip code in format of ##### or ######### (5 or 9 digit).
Please be aware that no hyphen is to be included. | | Identification | conditional  | A collection of one or more patient identifiers. For each occurrence, both \ and @Issuer are required. | | ID | mandatory  | A patient identification string. | | ID/@Issuer | mandatory  | A globally unique identifier representing the issuing authority for the Patient ID. | | UseCase | conditional  | Do not send for Clinical Direct Messaging. Supplemental guides may contain additional instructions for this field. Customers may receive messages with this field populated. |