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:

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