NAV Navbar
Messaging API
version 2.0
JSON
  • Introduction
  • Use Cases
  • Parameters
  • POST Direct Messages to Edge
  • Request
  • Response
  • Delivery Status Message Format
  • Messaging Status Endpoint
  • Direct Message Statuses
  • Errors
  • Introduction

    Welcome to the documentation for MedAllies Messaging API! This documentation provides information for MedAllies Direct clients to connect to our API allowing edge vendors to exchange encrypted direct messages with prompt notifications of their delivery via MDNs.

    The MedAllies Messaging API allows flexible Electronic Health Record (EHR) interoperability utilizing RESTful messages.

    If there are specific features that you need, please contact our Customer support center.

    We will also be releasing language wrappers for the API shortly, to facilitate development. If you have a specific language that you would like to see included, please contact our Customer support center.

    Adherence to our Terms and conditions is a requirement for using our API.

    Endpoints

    Base Url : https://api.medalliestest.com:9443/MessagingAPI

    Send Message : https://api.medalliestest.com:9443/MessagingAPI/dirmsg/send_ccda

    Authentication

    MedAllies uses API keys in order to grant access to the API.

    You should keep your API keys private and store them securely. Your API key/value pairs must be included in all API requested to the server in a header that looks like the following:

    Key: Content-Type Value: application/json
    Key: Authorization Value: < Authorization Type >:< User-name + Hashed or Encrypted Password >
    Auth Example:
    Key: Authorization Value: Basic VXNlcm5hbWU6UGFzc3dvcmQ
    

    Response Format

    The Messaging API allows REST calls, and returns a JSON structure.

    That outermost "layer" of the JSON structure contains 2 fields: - status: either "OK" or "Error" - result: typically an array in JSON representation

    Use Cases

    The MedAllies Messaging API can perform the following capabilities:

    • Create and send properly formatted message and post to the Messaging API

    • Receive an API Post from MedAllies for a Disposition Status Notification

    • Send payloads outside of CCDA (PDF or TXT File)

    • Receive payloads outside of CCDA (PDF or TXT File)

    • Send a multi-recipient Direct Message

    Parameters

    Required

    The following fields are required arguments to be included in the REST Message:

    • fromDirectAddress is the Direct Address of the Sending Edge.
      Format:jsmith@orgabbrev.medalliesdirect.net

    • toDirectAddress are the Direct Addresses of the Receiving Edge.
      Format:jsmith@orgabbrev.medalliesdirect.net

    • messageId is the Message ID assigned by the Sending Edge and is also used for delivery status tracking. messageId must be unique per message.
      e.g., "messageId": "urn:uuid:a2d59543-91f4-45a4-99ef-72d70da1e454",

    Optional

    A list of accepted optional fields are as follows:

    • emailAttachmentList is an array of the clinical documents (e.g., CCDA, PDF summaries, etc.), with each clinical document being Base64-encoded and described by the MIME type (attachmentClass) and a title

    • messageBody is an introductory note provided by the sending EHR

    • messageSubject is a subject of the message provided by the sending EHR

    • replyToMessageId allows correlation to the Message ID of the first Direct Messages in multiple exchanges (conversation) about the same patient / treatment combination

    • xdm allows the sending EHR system to specify that the message should be as the default metadata-rich XDM zip format (“xdm" : true) or for the messages to be sent as an SMTP message with raw attachments (“xdm" : false). This control is sometimes needed when the receiving HISP or EHR has special needs beyond standard Direct message formats.

    • the patientId and assigning_authority are the local patient IDs and Assigning Authority, as declared by the sending organization, and follows the logic of the HL7 V2.5 Identifier

    • all other fields beginning patient describe the demographics of patient in focus in the clinical documents

        patientAddressStreet1
        patientAddressStreet2
        patientAddressCity
        patientAddressState
        patientAddressZip
        patientDOB
        patientGender
        patientIdType
        patientLastname
        patientFirstname
        patientMiddlename
        patient_summary
    

    POST Direct Messages to Edge

    Authentication

    This authentication is basic and the credentials must be provided by Edge

    200 Response = Successful Consumption

    Example of Request Body for sending Direct Messages to Edge:

    {
      "messageInfo": {
        "messageId": "urn:uuid:efcb1520-33e0-11ea-a952-9610c7282913",
        "fromDirectAddress": "healthelinktest@hl.medalliesdirect.org",
        "toDirectAddress": [
          "qtac.dpp@hl.medalliesdirect.org"
        ],
        "transitTime": "2019-06-03T11:52:48.61882z"
      },
      "messageAttachmentList": [
        {
          "attachmentClass": "text/xml",
          "attachmentContent": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiIHN0YW5kYWxvbmU9Im5vIj8==",
          "attachmentTitle": "Qa_trunkdefcont: Transition of Care Consolidated CDA for Bryan Test",
          "attachmentSize": "28255"
        }
      ]
    }
    
    

    Example showing notification of a successful delivery:

    {
        "status": "status",
        "messageId": "messageId"
    } 
    

    Example showing notification of a failed delivery:

    {
        "status": "status",
      "failureReason":"failureReason",
        "messageId": "messageId"
    } 
    

    Request

    https://api.medalliestest.com:9443/MessagingAPI/dirmsg/send_ccda

    Request payload example

    {
    
        "fromDirectAddress" : "someuser@medalliesdirect.net",
    
        "toDirectAddress" : "someuser@medalliesdirect.net",
    
        "emailAttachmentList" : [
    
            {
    
                "attachmentClass" : "text/xml",
    
                "attachmentContent" : "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48Q2xpbmljYWxEb2N1bWVudCB...W5pY2FsRG9jdW1lbnQ+",
    
                "attachmentTitle" : "MR-Lumbar Spine without contrast_1"
    
            },
    
            {
    
                "attachmentClass" : "application/pdf",
    
                "attachmentContent" : "JVBERi0xLjYNJeLjz9MNCjM2IDAgb2JqDTw8L0xp...4cmVmDTExNg0lJUVPRg0=",
    
                "attachmentTitle" : "MR-Lumbar Spine without contrast_report"
    
            }
    
        ],
    
        "messageBody" : "Clinical Report for Patient Ralph Kramden. Please find attached clinical report",
    
        "messageId" : "urn:uuid:a2d59543-91f4-45a4-99ef-72d70da1e454",
    
        "messageSubject" : "F",
    
        "patientAddressStreet1" : "328 Chauncey Street",
    
        "patientAddressStreet2" : "Apt 3B",
    
        "patientAddressCity" : "Brooklyn",
    
        "patientAddressState" : "NY",
    
        "patientAddressZip" : "11233",
    
        "patientDOB" : "19160226",
    
        "patientGender" : "M",
    
        "patientId" : "22943847",
    
        "assigning_authority" : "2.16.840.1.113883.3.9999",
    
        "patientIdType" : "2.16.840.1.113669.2013.2.4.880061800.0",
    
        "patientLastname" : "Kramden",
    
        "patientFirstname" : "Ralph",
    
        "patientMiddlename" : "H",
    
        "patient_summary" : "Name (last, first middle): Kramden, Ralph H\nAddress: 328 Chauncey Street, Apt 3B, Brooklyn NY 11233\nGender: M\nDOB: 19160226",
    
        "replyToMessageId" : "2ea5021a-0c52-470a-8635-7aee90e5be34",
    
        "xdm" : true
    
    }
    
    

    To overwrite the HISP generated file name, include the attachmentFileName and/or xdmFileName. The extensions should not be added to the attachmentFileName or xdmFileName. If the xdmFileName is included, the file delivered will add -xdm.zip to conform to Direct Trust standards.

    Response

    When the EHR sends a message in to the /dirmsg/send_ccda service, the HISP responds synchronously with a brief acknowledgement with the following fields:

    1. messageiD
    2. status
    3. transactionId
    4. result

    Response example

    {
        "messageId": "urn:uuid:a2d59543-91f4-45a4-99ef-72d70da1e454",
        "status": "SUCCESS",
        "transactionId": "95f8ad81-061f-48d3-b1a2-af6cf8d9954e",
        "result": "Message parse successfully"
    } 
    

    Delivery Status Message Format

    The MedAllies HISP sends real-time, asynchronous delivery status messages to the sending EHR, to confirm that a message was delivered.

    Example showing notification of a successful delivery:

    {
        "Timestamp" : "2017-06-13T16:25:54.873043z",
        "Id" : "7d285434-2289-4214-928a-462314994789",
        "Status" : "Success",
        "Description" : "dispatched"
    }
    

    where:

    • Id is the original Message ID
    • Status is either Success or Error (with Description populated with the error reported by the HISP)

    Example showing notification of a failed delivery:

    {
        "Timestamp" : "2017-05-13T02:12:45.477491z",
        "Id" : "urn:uuid:263e022e-3ec0-11e8-90ce-f77da4f8427d",
        "Status" : "Error",
        "Description" : "9002: ERROR=NoTrustedRecipients"
    }
    

    Messaging Status Endpoint

    The delivery status can be queried by /dirmsg/status with the required query params of xdMsgId and fromDirectAddress.

    Example of the response

    [
      {
        "sender": "l9093@box216.madev.local",
        "recipient": "l9099@qa1.madev.local",
        "xdMsgId": "AVC32-fc440f05-3257-40c1-a3e8-a9b629f82735",
        "sendTime": "2018-11-27 13:15:04.0",
        "status": "FAILED",
        "failureReason": "9002: "
      }
    ]
    

    Direct Message Statuses

    The following are details for different Statuses shared between Sending and Receiving Edge Systems:

    1. PROCESSED - an asynchronous message has been sent by the HISP signifying a successful hand-off receipt of the sent message. Processed is not a final status of the message. Processed is followed by "Dispatched" (optionally - "Displayed", if the Receiving edge provides for it) or "Failed".

    2. LATE-PROCESSED - an asynchronous message signifying a successful hand-off of the sent message to the HISP has been sent outside of the allotted timeframe. (Currently set to 1 hour)

    3. FAILED - a "Failed" MDN has been generated and sent by the HISP to the Sending edge, signifying fatal errors encountered on delivering the message to the Receiving EDGE. (Currently set to 1 hour)

    4. FAILED-TO - a "Failed" MDN signifying fatal errors encountered on delivering the message to the HISP has been generated and sent by the to the Sending edge outside of the allotted timeframe. (Currently set to 1 hour)

    5. DISPATCHED - a "Dispatched" MDN has been generated and sent by the HISP to the Sending edge, signifying successful delivery of the message. "Dispatched" is a final status of the message. It may only be further updated to an optional status of "Displayed" (see below) as a read-receipt generated by the Receiving edge and passed along by the HISP. It cannot be overridden by any other message status.

    6. LATE-DISPATCHED - a "Dispatched" MDN signifying successful delivery of the message has been generated and sent by the Receiving HISP to the Sending edge outside of the allotted timeframe. (Currently set to 1 hour)

    7. DISPLAYED - a "Displayed" MDN has been generated by the edge and sent by the HISP to the Sending edge, signifying successful delivery and a read-receipt of the message. "Displayed" message status is optional and may be provided by the Receiving edge and passed along by the HISP. "Displayed" status cannot be overridden by any other message status.

    8. LATE-DISPLAYED - a "Displayed" MDN signifying successful delivery and a read-receipt of the message has been generated by the Receiving edge and sent by the Receiving HISP to the Sending edge outside of the allotted timeframe. (Currently set to 1 hour)

    Currently MedAllies HISP has a 1-hour timeframe to receive a final MDN ("Dispatched"/ "Displayed" (optionally)/ "Failed") from the edge or generate one on its behalf. If your message status doesn’t update to the final status after 1 hour from sending the message, please contact our Support Network.

    Errors

    Error Code Response Key Meaning
    400 Bad Request There was something wrong with your request.
    401 Unauthorized Your API key is incorrect.
    403 Forbidden You do not have access to the requested resource.
    404 Not Found The specified resource could not be found.
    429 Too many requests You've made too many API requests in a short time.
    500 Internal Server Error There was an issue on our end. Try your request again.
    503 Service Unavailable The API is offline for maintenance. Try again later.