Send a file via Redox Data Model API

If you haven’t already, check out our high-level summary and best practices for sending a file to an integrated system. The details below get into the specific “how-to” but it’s best to have a general idea before getting started. 

With the Data Model API, you can use the Notes or Results data model to send a file to your integrated system. This depends on the context of the file: 

• Use the Notes data model if you want to send clinical notes that a provider wrote about a patient or a general file related to the patient (e.g., a consent form signed by the patient or a JPG related to a patient’s chart).

  What to send with a Notes file

  With the Notes data model, most EHR systems require that you provide the patient identifier and basic demographic information (e.g., name, date of birth). But you may need to include some of these bonus details:

  • unique note ID
  • note type
  • provider authentication and authorization (i.e., whether the physician has authenticated and authorized the note to add it to the patient's chart)
  • visit number (to associate a note with a specific visit or area in the EHR system)

  Another possible alternative

  You can use the Media data model for sending files, but we recommend sticking with Notes. Here's a breakdown of why:

  • Notes can send files as plain or rich text, so the content is subject to each EHR system's rendering capabilities. In case the EHR system has search or natural language processing (NLP) capabilities, Notes may offer superior search and usability.
  • Media can typically send files like PDFs, images, or audio. But most EHR systems don't support the Media data model for diagnostic quality images, and DICOM files are above the size limits for Media.

• Use the Results data model if you want to send a file with test results or related to a patient’s labs. 

Each data model has their own supported fields and requirements. Below, we only highlight the fields you need to include for sending files. 

1. Encode the file as a base64 encoded string.
2. Populate the required document fields to include the encoded file in your request: 
   • In the Note.ContentType field, enter Base64 Encoded (as one of the supported values from the valueset).
   • In the Note.FileContents field, insert the base64 encoded string for the file.
   • In the Note.FileName field, enter the name of the file.
   • In the Note.DocumentType field, enter the type of document that should be associated with the file (e.g., consent form, treatment plan).
   • In the Note.DocumentID field, enter the unique identifier for this document.
   • In the Note.Provider.ID field, enter the ID of the provider responsible for the document.
3. Populate any of the other fields of the request with relevant data. Learn more about the available fields in the Notes data model.

   Example: Notes request

   1
   { 
   2
      …
   3
      "Note": {
   4
        "ContentType": "Base64 Encoded",
   5
        "FileContents": "XG82ZSC0aHUgd3F5IHlvdSBsaYU=",
   6
        "FileName": "Order Specific Note",
   7
        "DocumentType": "Clinical Note", 
   8
        "DocumentID": "b169267c-10c9-4fe3-91ae-9ckf5703e90l", 
   9
        "Provider": {
   10
          “ID”: "4356789876",  
   11
          …
   12
          }
   13
      …
   14
    }

   Expand

1. Encode the file as a base64 encoded string.
2. Populate the required document fields to include the encoded file in your request: 
   • In the Orders[].Results[].Value field, insert the base64 encoded string for the file.
   • In the Orders[].Results[].ValueType field, enter Encapsulated Data (as one of the supported values from the valueset).
   • In the Orders[].Results[].FileType field, enter a valid file type.
3. Populate any of the other fields of the request with relevant data. Learn more about the available fields in the Results data model.

   Example: Results request

   1
   {
   2
      …
   3
      "Orders": [
   4
        { …
   5
          "Results": [
   6
            { 
   7
              "Value": "XG82ZSC0aHUgd3F5IHlvdSBsaYU=",
   8
              "ValueType": "Encapsulated Data",
   9
              "FileType": "PDF",
   10
               …
   11
            }
   12
         ]
   13
        }
   14
      ]
   15
    }

   Expand

1. Encode the file as a base64 encoded string.
2. Populate the required document fields to include the encoded file in your request:
   • In the Media.FileType field, enter a valid file type.
   • In the Media.FileName field, enter the name of the file.
   • In the Media.FileContents field, insert the base64 encoded string for the file. 
   • In the Media.DocumentType field, enter the type of document that should be associated with the file (e.g., consent form, treatment plan).
   • In the Media.DocumentID field, enter the unique identifier for this document.
   • In the Media.Provider.ID field, enter the ID of the provider responsible for the document. 
   • In the Media.Availability field, enter the relevant value from the supported valueset (i.e., Available, Unavailable, Obsolete, Deleted, Cancelled).
3. Populate any of the other fields of the request with relevant data. Learn more about the available fields in the Media data model.

   Example: Media request

   1
   {   …
   2
      "Media": {
   3
        "FileType": "PDF",
   4
        "FileName": "Annual visit",
   5
        "FileContents": "XG82ZSC0aHUgd3F5IHlvdSBsaYU=",
   6
   	   "DocumentType": "Consent form",  
   7
        "DocumentID": "b169267c-10c9-4fe3-91ae-9ckf5703e90l",     
   8
        "DocumentID": "b169267c-10c9-4fe3-91ae-9ckf5703e90l",     
   9
        "Provider": {
   10
           “ID”: "4356789876",  
   11
           …
   12
           }
   13
        "Availability": "Available",
   14
       …
   15
       }
   16
    }

   Expand

For larger files, you must first upload them to Redox. Then, you can refer to the file in your requests.

1. Locate the file you want to upload.
2. Send your file to the Redox upload endpoint: 

   Example: Upload a file to Redox with the Data Model API

   1
   curl https://blob.redoxengine.com/upload \
   2
     -H "Authorization: Bearer " 
   3
     -X POST \
   4
     -F file=@file.pdf

   You must authenticate the API key as for a typical Data Model API request. Learn how to authenticate and initiate a request. 
3. If the upload is successful, you receive a 201 Created status with the URI reference to your file in the body of the response:

   Example: Binary response with the reference URL

   1
   {
   2
      "location": "https://blob.redoxengine.com/123456789"
   3
   }

4. Send the uploaded file via the same process for embedding a file. You only need to include the URI from the previous step instead of the base64 encoded file within the request. 
5. To check if the file uploaded successfully, log in to the Redox dashboard and check the log for the request. The uploaded file displays under the Process tab of the log.