Send a file via Redox Data Model API

Send a file to your connection(s) to provide clinical or administrative context for patients you share. Typically, you send a file to save to a patient’s chart. This article contains instructions for how to send a file with the Redox Data Model API.

With Redox, you can send files to your connection(s) with either of these two methods:

• Upload a file to a Redox blob endpoint, then include the URL reference (recommended). 
• Embed a file directly in the selected data model.

If you haven’t already, review general file sending info.

The data model you use depends on the context of the file. 

• The Notes data model is for a provider’s clinical notes or a general file related to the patient (e.g., a signed consent form or a patient-related JPG file). This data model sends 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.

  What to send with a Notes file

  With the Notes data model, EHR systems typically require that you provide the patient identifier and basic demographic information (e.g., name, date of birth). 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)

• The Results data model is for a patient’s test results or lab-related data. 
• The Media data model is for PDFs, images, or audio. However, most EHR systems don't support the Media data model for diagnostic quality images, and DICOM files typically exceed the size limits for Media. We recommend using Notes over Media.

Each data model has their own supported fields and requirements. In this how-to, we only highlight the required fields for each, but check out our data model reference docs for full specs.

• Decide which sending method to use (i.e., upload or embed a file).
• Decide which Redox data model to use (Notes, Results, Media).
• For free accounts choosing to upload and reference a file, log in to either a staging or production environment. Uploading isn’t available in free development environments. Talk to your Technical Account Manager about upgrading if you want to upload files in development.

Our recommended method is to upload a file to the Redox blob. Then, include a reference to the file in your request.

1. Locate the file you want to upload.
2. Authenticate an OAuth API key like you would for any Data Model API request. Learn how to authenticate and initiate a request. 
3. Send an HTTP request with your file to the Redox blob. The file should be uploaded with the file key, using the multipart/form-data content type. Learn more about multipart form submission.
   • The Redox-source-Id header is only required if you have multiple sources and you’re using an OAuth API key. Even though it’s a FHIR® header, it’s still supported for this scenario with the Data Model API. Learn about managing source details.

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

     bash

     Copy

     1
     curl https://blob.redoxengine.com/upload \
     2
       -H "Authorization: Bearer $API_TOKEN" \
     3
       -H "Redox-source-Id: {{SOURCE-ID}}" \
     4
       -X POST \
     5
       -F file=@file.pdf

     Example: Upload a file with the Redox Data Model API (Node.js)

     javascript

     Copy

     1
     const fs = require('fs');
     2
     
     3
     fs.openAsBlob('file.pdf')
     4
     .then((blob) => {
     5
       const body = new FormData();
     6
       body.append('file', blob)
     7
       return fetch('https://blob.redoxengine.com/upload', {
     8
         method: 'POST',
     9
         headers: {
     10
           'Redox-Source-Id': '{{SOURCE-ID}}',
     11
           'Authorization': 'Bearer $API_TOKEN'
     12
         },
     13
         body
     14
       })
     15
     })
     16
     .then((resp) => {
     17
       return resp.json()
     18
     }) 
     19
     .then((body) =>
     20
       console.log("blobfile URL:", body.URI)
     21
     )
4. If successful, you receive a 201 Created status with the URI reference to your file in the body of the response.
5. Send the uploaded file following the same instructions for embedding a file in the relevant data model below. In place of the base64 encoded string, include the URI from the previous step.
6. 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.

You can embed a file so long as the file fits within the size limit for the type of traffic. Check limits by traffic type.

The instructions for populating the request below are also used for uploading and referencing a file, except the URI is used instead of the base64 encoded string in all cases.

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

     Encoded files

     If you’re referencing an uploaded file instead of embedding a base64 encoded string, you should still populate the ContentType field with the Base64 Encoded value. The reason being that anything other than plain or rich text requires some kind of encoding and decoding to render. So all content types will be encoded unless it’s plain or rich text.

   • In the Note.FileContents field, insert the base64 encoded string for the file.

     Referencing an uploaded file

     If you’re referencing an uploaded file, enter the file URI instead of a base64 encoded string.

   • 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 Notes request with relevant data. Refer to the Notes schema for all the available fields.

   Example: Embed a file in the Notes data model

   json

   Copy

   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.

     Referencing an uploaded file

     If you’re referencing an uploaded file, enter the file URI instead of a base64 encoded string.

   • In the Orders[].Results[].ValueType field, enter Encapsulated Data (as one of the supported values from the value set).
   • In the Orders[].Results[].FileType field, enter a valid file type.
3. Populate any of the other fields of the Results request with relevant data. Refer to the Results schema for all the available fields.

   Example: Embed a file in the Results data model

   json

   Copy

   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. 

     Referencing an uploaded file

     If you’re referencing an uploaded file, enter the file URI instead of a base64 encoded string.

   • 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 value that describes the file's availability: Available, Unavailable, Obsolete, Deleted, Cancelled.
3. Populate any of the other fields of the request with relevant data. Refer to the Media schema for all the available fields.

   Example: Embed a file in the Media data model

   json

   Copy

   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
        "Provider": {
   9
           “ID”: "4356789876",  
   10
           …
   11
           }
   12
        "Availability": "Available",
   13
       …
   14
       }
   15
    }