NAV Navbar
Messaging API
version 2.1
JSON
  • Introduction
  • Outbound
  • Inbound
  • Delivery Status Notification
  • 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 healthcare interoperability utilizing RESTful messages.

    Please contact the MedAllies Support Center with Messaging API questions or enhancement requests.

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

    Use Cases

    Vendors can perform the following capabilities:

    • Post to the Messaging API to send properly formatted Direct message

    • Receive a RESTful API post from MedAllies for a Disposition Status notification

    • Send Non-CCDA Payload so long as they are base-64 encoded and application class has the correct media type specified.

    • Receive Payloads other than CCDA

    • Send a multi-recipient Direct Message

    • Request Direct Messages as XDM attachments or Non-XDM attachments

    Outbound

    URL

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

    Authentication

    {
    "Content-Type Value": "application/json",
    "Authorization" : "Basic VXNlcm5hbWU6UGFzc3dvcmQ"
    }
    

    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
    

    POST request Body

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

    Send Message payload example

    {
    
        "fromDirectAddress" : "john@medalliestestdomain.com",
    
        "toDirectAddress" : "smith@medalliestestdomain.com",
    
        "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" : "Custom messageSubject 3 . TXT file, XDM: false",
    
        "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,
    
        "asmEnabled" : true,
    
        "loincName" : "Referral Note",
    
        "loincValue" : "LOINC",
    
        "authorPerson" : "Doctor",
    
        "authorInstitution" : "Some Hospital^^^^^^^^^2.999.1.2.3.5.8.9.1789.45"
    
    }
    
    

    Multi recipient request payload example

    {
    
        "fromDirectAddress" : "someuser@medalliesdirect.net",
    
        "toDirectAddress" : "someuser@medalliesdirect.net,someotheruser@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
    
    }
    
    

    Required fields:

    Field name Description
    fromDirectAddress Direct Address of the Sending Edge. Format : john@medalliestestdomain.com
    toDirectAddress Direct Addresses of the Receiving Edge. Format : smith@medalliestestdomain.com
    Multi-recipient messages include all direct addresses of the Receiving Edges in this field separated by a comma. eg: "michael@orgabbrev.medalliesdirect.net,jsmith@orgabbrev.medalliesdirect.net"
    messageId 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"
    emailAttachmentList 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

    Optional fields:

    Field name Description
    attachmentClass media type of the attachment file
    attachmentFileName attachment/name (e.g., attachment/ccda)
    xdmFileName File name of xdm package
    asmEnabled when set to "true" it enables the HISP to send a 'Dispatched' DSN back to the Sender.
    messageBody an introductory note provided by the sending EHR
    messageSubject 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.
    assigning_authority Assigning Authority (as declared by the sending organization, and follows the logic of the HL7 V2.5 Identifier)
    patientId patient id (as declared by the sending organization, and follows the logic of the HL7 V2.5 Identifier)
    patientAddressStreet1 patient street address 1
    patientAddressStreet2 patient street address 2
    patientAddressCity patient city
    patientAddressState patient state
    patientAddressZip patient zip code
    patientDOB patient date of birth
    patientGender patient gender
    patientIdType patient id type
    patientLastname patient last name
    patientFirstname patient first name
    patientMiddlename patient middle name
    patient_summary patient summary
    loincName loincName
    loincValue loincValue
    authorPerson authorPerson
    authorInstitution authorInstitution

    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:

    Response example

    {
        "messageId": "urn:uuid:a2d59543-91f4-45a4-99ef-72d70da1e454",
        "status": "SUCCESS",
        "transactionId": "95f8ad81-061f-48d3-b1a2-af6cf8d9954e",
        "result": "Message parse successfully"
    }
    
    Field name Description
    messageId 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",
    status Status of the message, e.g. PROCESSED, DISPATCHED, SUCCESS, FAILED etc.
    transactionId Unique ID given to the transaction.
    result Description which describes if the message is parsed successfully or not.

    Inbound

    URL

    to be provided by Vendor

    MedAllies HISP provides the ability for EHR vendors to receive Direct messages in JSON format. The endpoint is provided by the vendor and is associated to a Direct address. Authentication credentials is provided by the EHR vendor. On successful deliver to the endpoint, the EHR edge endpoint must return a 200 http status.

    Authentication

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

    {
    "Content-Type Value": "application/json",
    "Authorization" : "Basic VXNlcm5hbWU6UGFzc3dvcmQ"
    }
    

    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 >:< key is a shared secret provided by the user >
    Auth Example:
    Key: Authorization Value: Basic VXNlcm5hbWU6UGFzc3dvcmQ
    

    POST request Body

    The EHR edge endpoint must receive Direct Message data in the following JSON format: ->

    Send Message payload example

    {
    
        "fromDirectAddress" : "john@medalliestestdomain.com",
    
        "toDirectAddress" : "smith@medalliestestdomain.com",
    
        "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" : "Custom messageSubject 3 . TXT file, XDM: false",
    
        "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,
    
        "asmEnabled" : true
    
    }
    
    

    Delivery Status Notification

    Delivery status notifications can be retrieved either through an API get request or asynchronously through a post request to a vendor specified endpoint.

    Asynchronous Delivery Status Notification

    Example showing notification of a successful delivery:

    {
        "Timestamp" : "2017-06-13T16:25:54.873043z",
        "Id" : "7d285434-2289-4214-928a-462314994789",
        "Status" : "Success",
        "Description" : "dispatched",
        "Disposition" : "action/MDN-sent-automatically;dispatched"
    }
    

    Example showing notification of a successful delivery:

    {
        "Timestamp" : "2017-06-13T16:25:54.873043z",
        "Id" : "7d285434-2289-4214-928a-462314994789",
        "Status" : "Success",
        "Description" : "processed",
        "Disposition" : "action/MDN-sent-automatically;processed"
    }
    

    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",
        "Disposition" : "action/MDN-sent-automatically;failed"
    }
    

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

    where:

    Id is the original Message ID

    Status is either Success or Error (with Description populated with the error reported by the HISP)

    Get API Request

    Response:

     {
        "sender":"john@medalliestestdomain.com",
        "recipient":"smith@medalliestestdomain.com",
        "xdMsgId":"urn:uuid:f729433a-7b5e-11ea-83f9-852dc7282913",
        "sendTime":"2020-04-10 15:10:39.0",
        "status":"PROCESSED"
      }
    

    Response:

     {
        "sender": "john@medalliestestdomain.com",
        "recipient": "smith@medalliestestdomain.com",
        "xdMsgId": "AVC32-fc440f05-3257-40c1-a3e8-a9b629f82735",
        "sendTime": "2018-11-27 13:15:04.0",
        "status": "FAILED",
        "failureReason": "9002: "
      }
    

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

    URL: https://api.medalliesdirect.com/MessagingAPI/dirmsg/status?xdMsgId=urn:uuid:f729433a-7b5e-11ea-83f9-852dc7282913&fromDirectAddress=john@medalliestestdomain.com

    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. 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)

    3. 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)

    4. 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.

    5. 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.

    6. SMTPINIT - The Sending HISP has successfully sent out a message. This step precedes receiving a "Dispatched" or "Failed" MDN from the Recipient, at which point the message status will update to the MDN status. "SMTPINIT" is an intermediate status which can last up to one hour. If a "DISPATCHED" or "FAILED" MDN is not received within an hour, the status is changed to "FAILED-TO."

    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 does not update to the final status after 1 hour from sending the message, please contact our Support Center.

    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.