Send a file via Redox Data Model API

If you haven’t already, review best practices for sending a file to your connection. This article contains instructions for how to send a file with the Redox Data Model API specifically. You can either:

• embed a file directly in the Notes, Results, or Media data models; or
• (recommended) upload a file to a Redox blob endpoint, then include the URL reference in the Notes, Results, or Media data models. 

You can embed a file within the Notes or Results data model, so long as the file fits within the size limit for the type of traffic. Check limits by traffic type.

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

• The Notes data model can send 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).

  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)

• The Results data model can send a file with a patient’s test results or lab-related data. 

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.

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
        "DocumentID": "b169267c-10c9-4fe3-91ae-9ckf5703e90l",     
   9
        "Provider": {
   10
           “ID”: "4356789876",  
   11
           …
   12
           }
   13
        "Availability": "Available",
   14
       …
   15
       }
   16
    }

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. Send an HTTP request with your file to the Redox upload endpoint. The file should be uploaded with the file key, using the multipart/form-data content type. Learn more about multipart form submission. You must authenticate the API key like you would for a typical Data Model API request. Learn how to authenticate and initiate a request. 

   Development not available for free accounts

   Upload functionality isn’t available in development environments if you have a free Redox account. Talk to your Technical Account Manager about upgrading if you want to upload files from development.

   Multiple sources and OAuth API keys

   If you have multiple sources and you're using an OAuth API key, you'll need to add the FHIR® Redox-Source-Id header when you're uploading a file to the Redox blob. 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
     #Include the FHIR header for source ID if you have more than 1 source with an OAuth API key
   4
     -H "Redox-source-Id: {{source-id}}" \
   5
     -X POST \
   6
     -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 {{access-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
   )
3. If successful, you receive a 201 Created status with the URI reference to your file in the body of the response.
4. Send the uploaded file following the same instructions for embedding a file in the relevant data model. But in place of the base64 encoded string, include the URI from the previous step.
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.