--- title: Integration and Production slug: xdr/guide/integration-and-production docTags: createdAt: 2026-07-30T21:09:38.919Z --- The following section defines technical and support elements needed to achieve certification to move XDR-based messaging into production, along with our Integration, Compliance, and Certification processes. ## Integration Process When a customer begins integrating a Surescripts product into their application(s), they will be provided access to all the Surescripts documentation pertaining to the product being implemented. In addition, customers will be provided access to the staging environment to design, develop and test the product integration within their application. :::hint{type="info"} **Note:** The time frame of the project can vary depending on the customer's resource allocation for the project. ::: **Meeting Requirements** During Integration, customers will ensure their system has met all product requirements. The Certification Testing will focus on message format, application workflow and display in accordance with Surescripts documentation and the associated Application Certification Requirements (ACRs). For requirements, consider the following: - Surescripts ACRs are required to be met to achieve production status on the Surescripts network and will be enforced as part of certification. - To ensure high-quality transactions, Surescripts applies additional business rules above and beyond the NCPDP schema defined requirements that will cause a message to be successful or rejected. - Surescripts test cases do not cover all possible scenarios in production. Customers are responsible for testing any other applicable scenarios specific to their production environment. - In accordance with the customer’s legal agreement with Surescripts, each customer is responsible for ensuring compliance with all applicable laws including, but not limited to, local and state laws/regulations where doing business. Upon successful completion of certification and, when applicable, other pre-production network requirements (e.g., Identity Proofing, Attestations, DEA audit), customers will be enabled in production. ## Transition to Production Once message validation testing is complete and the contract is approved by the Surescripts Certification Review Board, the customer is ready to move into production. Surescripts will configure the production connection and ensure successful operations with the customer. Prior to transition into production, Surescripts Account Management will work with the customer and internal Surescripts teams to review the following items: - **Production support contacts** :::Paragraph{indent="1"} To be captured in an Escalation Matrix—a tool that specifies how Surescripts should contact customers for support needs, including case routing and escalation paths. ::: - **Support process and training** - **Support hours** :::hint{type="info"} **Note:** The Escalation Matrix for use by Surescripts customers can be found in the *Surescripts* *Network Operations Guide*. ::: ## Surescripts Terminology Usage The following table outlines terminology usage for this guide. | **Term** | **Term Usage** | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | must | Requirements that are enforced as part of the production code or by Surescripts business rules. Some business rules reside in the Element Details section of this guide. | | shall | The requirements customers are required to meet in order to be certified on the Surescripts network. These requirements will be enforced as part of certification, not through business rules. | | should | Used for guidance and best practices to produce superior results and enhance electronic messaging. Best practices can also be found in the Best Practice sections. Customers are encouraged, but not required, to meet best practices in order to be certified on the Surescripts network. | | C.### | Designates a Surescripts Clinical Direct Messaging ACR. | ## Communication Rules Please refer to the Connectivity and Authentication Guide for details regarding communication and security protocol requirements as well as references to all links and IP addresses associated with Surescripts services. For the network to be reliable, there are communication rules to which all customers must adhere. ## Connectivity and Mutual TLS (mTLS) Surescripts requires Mutual Transport Layer Security (mTLS) authentication for XDR. Mutual authentication means both parties in the connection authenticate each other: the client authenticates the server, and the server authenticates the client. mTLS is standard across Surescripts products and is a common source of setup issues, so the direction-specific roles are described below. The complete certificate and connectivity requirements are maintained in the Connectivity and Authentication Guide, which is the authoritative source and must be followed for implementation. For XDR, mTLS applies in both directions of exchange, and the customer's role differs by direction: **When the customer sends to Surescripts** (customer-initiated), the customer acts as the client and presents a Surescripts-authorized client certificate. Surescripts signs this certificate from a Certificate Signing Request (CSR) the customer submits. See the Connectivity and Authentication Guide, Authentication section, "Customer Client-Side Certificates," for the CSR and client-certificate requirements. **When the customer receives from Surescripts** (Surescripts-initiated), the customer acts as the server and presents a server certificate that Surescripts validates. See the Connectivity and Authentication Guide, Authentication section, "Customer Server-Side Certificates," for the server-certificate requirements. Because XDR connections authenticate with mTLS, they do not require IP allow-listing. :::hint{type="info"} **Note:** The TLS protocol version, cipher requirements, certificate specifications (including key length, subject fields, and acceptable certificate authorities), certificate renewal, and IP address handling are all governed by the Connectivity and Authentication Guide. Refer to that guide rather than assuming any value. ::: ## Message Size The maximum size for a single XDR message, including all attachments, is 20 MB. A message larger than 20 MB is rejected at the transport channel before any XDR processing occurs, so the sender receives a transport-level failure rather than an XDR application-level error (see [XDR-Based Messaging Errors](docId:6daoSZCLi671QoVLxx3uD)). 20 MB is also the practical ceiling for broad interoperability, because not all systems in the exchange ecosystem accept messages at or near that size. Where a recipient’s capacity is unknown, design for smaller messages. ## Timeouts For timeouts, consider the following: When sending a message to Surescripts, the initiator should set the HyperText Transfer Protocol (HTTP) timeout to no less than 30 seconds. A receiving system must return a valid synchronous response - a Provide and Register Document Set-b Response indicating success, or an error response - within 24 seconds. Setting the sender's timeout to at least 30 seconds allows the receiving system adequate time to generate its response within the required 24 seconds. When a message is accepted for delivery but its final delivery status is not yet known, a Delivery Status Notification (DSN) is expected to follow. If a follow-up DSN is not received within 60 minutes, the message times out and Surescripts generates a DSN Failure to the sender. :::hint{type="info"} **Note:** See [Message Notifications and Tracking](docId\:daGa7Uw8ataRiYlZ3RtU9) for how synchronous responses and DSNs work together. ::: ## UTC Time Format By using Coordinated Universal Time (UTC), the receiver of a message will know the time regardless of their time zone. For example, if a message was sent from Boston at 5:30 PM EDT (Eastern Daylight Time), the time would be sent as 21:30 UTC. If this message was received in Chicago CDT (Central Daylight Time), the 21:30 UTC could be converted to the local CDT time of 4:30 PM. UTC time must be synchronized with the National Institute of Standards and Technology (NIST), and the difference must be less than one minute. When sending only a date (not date and time), it should be sent in the local time zone, and the receiver should interpret it in their local time. Neither party should attempt to convert the date to UTC. The format of date/time fields in the XML schema must use the `xsd:dateTime` format: `CCYY-MM-DDTHH:MM:SS.FZ`, where the UTC time zone may be specified as `Z, +00:00`, or `-00:00`. For example, `2026-01-15T16:09:04.5Z` represents 16 hours, 09 minutes, 04 seconds, and 5 fractional seconds. The fractional seconds portion is not required. For simple date fields that do not include the time portion, the format is `CCYY-MM-DD`. ## Character Set | **The character set contains ASCII values 32 – 126, which includes:** | | | --------------------------------------------------------------------- | ----------------------------------------------------------------------- | | Symbols | ! " # $ % & ' ( ) \* + , - . / : ; \< = > ? @ \[ \ ] ^ \_ \` \{ \| } \~ | | Numerals | 0 to 9 | | Letters, upper and lower case | A to Z, a to z | UTF-8 is the required character encoding for XML. Other encoding formats are not supported by Surescripts. :::hint{type="info"} Surescripts recommends that customers declare their UTF-8 formatting in the message header. ::: ## XML Escape Characters XML uses certain characters to describe the structure of the document. When an element value needs to include one of these special characters, the character must be replaced with its predefined entity representation. The quote and apostrophe only need to be escaped when used in an attribute. Most XML processor libraries handle this replacement automatically. | **Character** | **Character Name** | **XML Escape** | | ------------- | ------------------ | -------------- | | " | Quote | \" | | ' | Apostrophe | \' | | & | Ampersand | \& | | \< | Less than | \< | | > | Greater than | \> | :::hint{type="info"} **Note:** String lengths are calculated based on the un-escaped value. For example, >98 degrees is encoded as \>98 degrees but is counted as a string length of 11, not 14. ::: ## Compliance The goal of Surescripts is efficiency and consistency across the network so all customers can meet the highest measures of patient safety, end-to-end reliability, and quality. To ensure that customers comply with and adhere to the approved certification requirements, Surescripts: - Monitors customers in production to ensure all network customers remain in compliance with certification requirements and contractual terms. - Initiates a remediation process for identified compliance issues. To ensure network and patient safety, customer agrees to notify Surescripts of any modifications through use of the Surescripts recertification form. Upon receipt of this form, changes will be reviewed, and a determination made as to what (if any) level of certification may be required before being placed into production. When changes are made to a customer’s implementation, the customer should advise their account manager. The customer will be given a recertification guide to provide details regarding the changes made. Upon receipt of the completed document, the details will be reviewed, and a determination will be made as to what (if any) level of recertification is necessary. As a reminder, Surescripts conducts certification with customers to ensure the application adheres to network requirements. Surescripts will enforce mandatory fields as required by the Standards body and Surescripts guide requirements. To maximize interoperability, customers are recommended to support optional fields that have been created to address gaps in discrete data needs and the many solutions that are in place for the benefit of the receiver. Surescripts encourages, but does not guarantee, the use of optional discrete fields to support end user workflows. This guide is intended for certification on our network only and is not intended to ensure compliance with state and federal law. In accordance with the customer’s legal agreement with Surescripts, each customer is responsible for conducting its own due diligence to ensure compliance with all applicable laws and requirements, including, but not limited to, local and state laws and regulations in which the customer’s application is deployed and used.