DocumentReference API on Epic R4 Gateway

The interopiO Epic R4 Gateway allows a client to attach PDF files to a patient's chart. This is required in two main scenarios:


1. Patient questionnaire for Appointments 

2. Provider notes from the Practitioner at the end of an appointment


In order to use this feature, the data adapter must be configured with the hl7OverHttpEndpoint to write HL7v2 messages to Epic. 

In order for this feature to work, the app connected to Epic should have HL7v2 enabled as well as DocumentReference write enabled. 

To be able to attach a PDF, the sample DocumentReference API is as below. The maximum limit to attach is 40MB

This needs to be POSTed to the interopiO Epic R4 Gateway  with an attachment with DocumentReference.content[0].attachment.contentType=application/pdf

The main items to be provided are:

  • type: a coding representing the PDF in the type field. Here the example displays a Progress note.
  • date: Date/time with timezone. This is the created date to be attached to the submitted document. The provided value with timezone is converted back to Epic's required format with date/time and timezone.
  • author: A reference to the Practitioner with the practitioner's FHIR ID in Epic. This is an optional element for the patient questionnaire scenario.
  • subject: A reference to the Patient with the Patient's FHIR ID in Epic.
  • masterIdentifier: A universally unique identifier usually a GUID which will become the document id submitted.
  • context.encounter.identifier.value: This is the encounter id for the appointment. It can be retrieved from the SMART launch using a token. If the application is not using this API via a SMART launch, then this is the CSN value that is returned from Epic when an Appointment is scheduled. 
  • data: This is the PDF data that is Base 64 encoded.
  • content[0].attachment.contentType=application/pdf


    "resourceType": "DocumentReference",
    "docStatus": "final",
    "type": {
        "coding": [{
            "system": "",
            "display": "Progress Note"
        "text": "Progress Note"
    "date": <DATE_TIME_WITH_TIMEZONE>,// a "created" date to attached to the submitted document
    "author": [
            "reference": "Practitioner/{{practitioner_fhir_id}}"
    "subject": {
        "reference": "Patient/{{patient_fhir_id}}"
    "masterIdentifier": {
        "value": "{{$guid}}"
    "context": {
        "encounter": [
                "identifier": [
                        "use": "usual",
                        "system": "urn:oid:1.2.840.114350.",
                        "value": "<CSN_RETURNED_IN_APPOINTMENT_RESOURCE>"
    "content": [
            "attachment": {
                "contentType": "application/pdf",
                "language": "en",
                "title": "<SOME TITLE>",
                "data": <BASE_64_ENCODED_PDF_DATA>"JVBERi0xLjMNJeLjz9MNCjExIDAgb2JqDTw8L0xpbmVhcml6ZWQgMS9MIDU4MzczNy9PIDE0L0UgODc5NTIvTiAyL1QgNTgzMzk3L0ggsUHRANSwLZ9fZ2pBjCZOfNh8enTjB8zBtvk4n9oyOLZ92QoZ3tX5vrmBepaNxJmNjlRZynWZCg8d0GGkLcfV1o2vaX/5bVKN1ihdqi8XVWo+kKq6KmxtXK5sTt0ZeEdfq44lrU5THHVLOjOtVlmm/4Gdov1WWav9QlMYLr/"
0 out of 0 found this helpful



Please sign in to leave a comment.