Send a file via the Redox FHIR API

Last updated: Jan 19, 2024

If you haven’t already, check out our summary and best practices for sending a file to your connection.

This article contains instructions for how to send a generic file with the Redox FHIR® API specifically. If you want to send results-related documents, learn how to send results or vitals.

You can either:

  1. embed a file less than 10 MB directly in the DocumentReference$documentreference-create request; or
  2. upload a file to a Redox endpoint with the Binary resource, then include the URL reference in the DocumentReference$documentreference-create request.

Embed a file

Send a file less than 10 MB to your connection in one API request. 

  1. Encode the file as a base64 encoded string.
  2. Use DocumentReference$documentreference-create to send the uploaded file to your connection. Refer to the DocumentReference schema for all the requirements.
  3. In the headers:
    • Replace {environmentFlag} with Development, Staging, or Production respectively.
    • Replace {API_TOKEN} with your access token.
    • Replace {destinationSlug} with the human-readable safe name for the intended destination.
  4. Populate the entry.resource.content.attachment fields to include the encoded file: 
    • In the contentType field, enter a valid MIME typeLearn 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
      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
      "data": "XG82ZSC0aHUgd3F5IHlvdSBsaYU="
      21
      }
      22
      }
      23
      ]
      24
      }
      25
      },
      26
      ...
      27
      ]
      28
      }'
  5. Send the populated request to your connection’s EHR system.
  6. 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.

Upload and reference a file

For larger files, you must first upload them to Redox using the FHIR® Binary resource. Then, you can refer to the file in a DocumentReference$documentreference-create request to your connection.

  1. Locate the file you want to upload.
  2. Upload your file to the Redox upload endpoint using the FHIR® Binary resource.
    • Replace {environmentFlag} with Development, Staging, or Production respectively.
    • Replace {API_TOKEN} with your access token.
    • 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
      1
      curl --location
      2
      --request POST 'https://api.redoxengine.com/fhir/R4/redox/{environmentFlag}/Binary' \
      3
      --header 'Authorization: Bearer ${API_TOKEN}' \
      4
      --data-binary 'file.pdf'
  3. If the 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
    1
    {
    2
    "location": "https://blob.redoxengine.com/123456789"
    3
    }
  4. Use DocumentReference$documentreference-create to send the uploaded file to your connection. Refer to the DocumentReference schema for all the requirements.
  5. Include the required entry.resource.content.attachment fields with the URL reference to the file you already uploaded: 
    • In the url field, enter the URL reference from the Binary response. 
    • In the contentType field, enter a valid MIME typeLearn 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
      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
      }'
  6. Send the populated request to your connection’s EHR system.
  7. 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.