Send a file via the Redox FHIR 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 generic file with the Redox FHIR® API. If you want to send results-related documents, learn how to send results or vitals.

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.

To upload a file to the Redox endpoint, use the Binary resource, then include the URL reference in the DocumentReference$documentreference-create operation.

To embed a file, use the DocumentReference$documentreference-create operation.

• Decide which sending method to use (i.e., upload or embed a file).
• 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 endpoint using the FHIR® Binary resource. Then, refer to the file in DocumentReference$documentreference-create.

1. Locate the file you want to upload.
2. Authenticate an OAuth API key like you would for any FHIR® API request. Learn how to authenticate and initiate a request. 
3. Upload your file to the Redox upload endpoint using the FHIR® Binary resource.

   Support for the FHIR Binary resource

   We only support the Binary resource for uploading files to Redox. So you won't find it in our API reference docs, but you can read about the FHIR® Binary resource in HL7's docs.

   • Replace {{ENVIRONMENT-FLAG}} with Development, Staging, or Production respectively.
   • Replace $API_TOKEN with your access token.

     API token

     If you haven't gotten an access token yet, learn how to authenticate an OAuth API key.

   • Add the Redox-source-Id header if you have more than one source in your environment. Learn about managing source details.
   • Keep redox in the slug. That portion routes the request to the appropriate Redox upload endpoint.

     Example: Upload a file to Redox with the Binary resource

     bash

     Copy

     1
     curl --location 
     2
     --request POST 'https://api.redoxengine.com/fhir/R4/redox/{{ENVIRONMENT-FLAG}}/Binary' \
     3
     --header 'Authorization: Bearer $API_TOKEN' \
     4
     --header "Redox-source-Id: {{SOURCE-ID}}" \
     5
     --data-binary 'file.pdf'
4. If the file upload is successful, you receive a 201 Created status. The reference URL is in the location header of the Binary response.

   Example: Binary response with the reference URL

   json

   Copy

   1
   {
   2
      "location": "https://blob.redoxengine.com/123456789"
   3
   }
5. Reference the uploaded file in a DocumentReference$documentreference-create request to your connection. Refer to the DocumentReference schema for all the requirements.
   • Include the required entry.resource.content.attachment fields with the URL reference to the uploaded file: 
     • In the url field, enter the URL reference from the Binary response. 
     • In the contentType field, enter a valid MIME type. Learn more about MIME types for files.
     • (Optional) In the title field, enter the name of the file.

       Example: Reference the uploaded file in DocumentReference$documentreference-create

       bash

       Copy

       1
       curl 'https://api.redoxengine.com/fhir/R4/{destinationSlug}/{environmentFlag}/DocumentReference/$documentreference-create' \
       2
       --request POST \
       3
       --header 'Authorization: Bearer $API_TOKEN' \
       4
       --header 'Content-Type: application/fhir+json' \
       5
       --data '{
       6
         "resourceType": "Bundle",
       7
         ...
       8
         "entry": [
       9
           ...
       10
           {
       11
             ...
       12
             "resource": {
       13
               "resourceType": "DocumentReference",
       14
               ...
       15
               "content": [
       16
                 {
       17
                   "attachment": {
       18
                     "contentType": "application/pdf",
       19
                     "title": "Order Request",
       20
                     "url": "https://blob.redoxengine.com/123456789"
       21
                   }
       22
                 }
       23
               ]
       24
             }
       25
           },
       26
           ...
       27
         ]
       28
       }'

       Abbreviated code example

       This DocumentReference$documentreference-create example is abbreviated to highlight the file portion specifically. For a fuller example, refer to the DocumentReference schema.

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 within the DocumentReference resource, so long as the file fits within the size limit for the type of traffic. Check limits by traffic type.

1. Encode the file as a base64 encoded string.
2. Authenticate an OAuth API key like you would for any FHIR® API request. Learn how to authenticate and initiate a request. 
3. Embed the uploaded file in a DocumentReference$documentreference-create request to your connection. Refer to the DocumentReference schema for all the requirements.
   • Replace {{ENVIRONMENT-FLAG}} with Development, Staging, or Production respectively.
   • Replace $API_TOKEN with your access token.
   • Replace {{DESTINATION-SLUG}} with the human-readable safe name for the intended destination.
   • Add the Redox-source-Id header if you have more than one source in your environment. Learn about managing source details.
   • Populate the entry.resource.content.attachment fields to include the encoded file: 
     • In the contentType field, enter a valid MIME type. Learn more about MIME types for files.
     • In the data field, insert the base64 encoded string for the file. 
     • (Optional) In the title field, enter the name of the file.

       Example: Embed a file in DocumentReference$documentreference-create

       bash

       Copy

       1
       curl 'https://api.redoxengine.com/fhir/R4/{{DESTINATION-SLUG}}/{{ENVIRONMENT-FLAG}}/DocumentReference/$documentreference-create' \
       2
       --request POST \
       3
       --header 'Authorization: Bearer $API_TOKEN' \
       4
       --header 'Content-Type: application/fhir+json' \
       5
       --data '{
       6
         "resourceType": "Bundle",
       7
         ...
       8
         "entry": [
       9
           ...
       10
           {
       11
             ...
       12
             "resource": {
       13
               "resourceType": "DocumentReference",
       14
               ...
       15
               "content": [
       16
                 {
       17
                   "attachment": {
       18
                     "contentType": "application/pdf",
       19
                     "title": "Order Request",
       20
                     "data": "XG82ZSC0aHUgd3F5IHlvdSBsaYU="
       21
                   }
       22
                 }
       23
               ]
       24
             }
       25
           },
       26
           ...
       27
         ]
       28
       }'

       Abbreviated code example

       This DocumentReference$documentreference-create example is abbreviated to highlight the file portion specifically. For a fuller example, refer to the DocumentReference schema.

4. To check if the embedded file sent successfully, log in to the Redox dashboard and check the log for the request. The embedded file displays in the log payload.