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

  To add a file to a patient's chart 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). They may also require relevant provider information like the note type, unique note ID, and whether or not the note has been authenticated by a physician and is authorized to be shared in the patient’s chart.  

  To associate a note with a specific visit or area in the EHR system, you may also need to provide a visit number.

  Another possible alternative

  You can also use the Media data model for sending a general file, but we recommend sticking with the Notes data model.

  Notes can send files as plain or rich text, so the content is subject to the rendering capabilities of each individual EHR system. Notes may also offer superior searchability and usability (if the EHR system has search or natural language processing [NLP] capabilities). Media can typically used for files like PDFs, images, or audio files. For images, though, most EHR systems don't use the Media data model to receive 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.

   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
    }

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.

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

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.

   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
    }

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: 

   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:

   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.