# Send results or vitals via the Redox FHIR API

Send results or vitals to your connection(s) to provide clinical context for patients you share. This article describes how to save vitals or diagnostic results with the <u>**Redox FHIR API**</u>. If you want to send generic files, [learn how to send a file](/how-to-use-redox/send-a-file-via-the-redox-fhir-api) instead. 

If you haven’t already, check out these high-level best practices: 

- [Save vitals to a patient's chart](/fhir-api-actions/results-and-vitals/save-vitals-to-a-patients-chart).
- [Save diagnostic results to a patient's chart](/fhir-api-actions/results-and-vitals/save-diagnostic-results-to-a-patients-chart).

## Supported methods for sending files

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.

|                 | Upload and reference file | Embed file |
| --------------- | ------------------------- | ---------- |
| Best for | Regularly sending large files.This is our recommended method since it improves our ability to process the request without errors. | Occasionally sending small files. |
| File size limit | Up to __30 MB__. The file limit is separate from the overall request limit. For example, if the request limit is 10 MB, the uploaded file doesn’t need to fit within that threshold. | Must fit within the request’s size limit. [Check limits by traffic type](https://docs.redoxengine.com/permalink/6KOwEzjE4jb2DBnQf6PBky/#message-and-file-size-limits). *Best practice*: We recommend not embedding files over __200 KB__.|
| Encoding | base64. Redox handles encoding the file. | base64. You must encode the file yourself. |
| Environment type | *For paid accounts*, available in any environment. *For free accounts*, only available in __staging__ or __production__. If you try to upload files in a development environment with a free account, we return a 403 Forbidden error. | Available in any environment. |
| Available file download in the Redox dashboard | Yes. | No. |

If you haven’t already, [review general file sending info](https://docs.redoxengine.com/basics/data-exchange-with-redox/sending-a-file/). 

## Which FHIR operation to use

You can use either supported method for sending results and vitals information with these operations: 

- [`DiagnosticReport$diagnosticreport-create`](https://docs.redoxengine.com/permalink/c216c7e0-cff3-545a-98cc-ca2fde009158-$diagnosticreport-create): Use for diagnostic tests (e.g., lab tests, pathology, imaging).
- [`Observation$observation-create`](https://docs.redoxengine.com/permalink/47b3094a-cbe7-50c1-bb36-f190e581e0eb-$observation-create): Use for individual results, findings, or measurements (e.g., vitals, imaging results, lab results, device measurements).

## Prerequisites

- Decide which sending method to use (i.e., upload or embed a file).
- Decide which FHIR operation to use (`$diagnosticreport-create`, `$observation-create`).
- _For free accounts choosing to upload and reference a file_, log in to either a <u>**staging**</u> or <u>**production**</u> 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.

## Upload and reference a file

Our recommended method is to upload a file to the Redox endpoint using the FHIR `Binary` resource. Then, refer to the file in either the `DiagnosticReport` or `Observation` resource.

1. Locate the file you want to upload.
2. 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. You won’t find it in our API reference docs, but you can [read about the FHIR Binary resource](https://build.fhir.org/binary.html) in HL7’s docs.


   - Replace `{{ENVIRONMENT-FLAG}}` with `Development`, `Staging`, or `Production`.
   - 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](/api-reference/redox-data-model-api/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](/basics/data-exchange-with-redox/Managing-source-details-in-outgoing-requests).
   - 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
curl --location 
--request POST 'https://api.redoxengine.com/fhir/R4/redox/{{ENVIRONMENT-FLAG}}/Binary' \
--header 'Authorization: Bearer $API_TOKEN' \
--header "Redox-source-Id: {{SOURCE-ID}}" \
--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
{
   "location": "https://blob.redoxengine.com/123456789"
}

```


4. Use the FHIR operation you want for sending results or vitals (`$diagnosticreport-create`, `$observation-create`).
5. Include the required `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 type**. [Learn more about MIME types for files](https://docs.w3cub.com/http/basics_of_http/mime_types/complete_list_of_mime_types.html).
   - (Optional) In the `title` field, enter the **name of the file**. 


**Example: Reference an uploaded file in DiagnosticReport$diagnosticreport-create**

```bash
curl 'https://api.redoxengine.com/fhir/R4/{{DESTINATION-SLUG}}/{{ENVIRONMENT-FLAG}}/DiagnosticReport/$diagnosticreport-create' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'Content-Type: application/fhir+json' \
--data '{
  "resourceType": "Bundle",
  ...
  "entry": [
    {
      "resource": {
        "eventUri": "https://fhir.redoxengine.com/EventDefinition/DiagnosticReportCreate",
        "resourceType": "MessageHeader",
        ...
        "resource": {
          "resourceType": "DiagnosticReport",
          "presentedForm": [
            {
              "contentType": "application/pdf",
              "title": "Lab Results",
              "url": "https://blob.redoxengine.com/123456789"
            }
          }
        ]
      }
    },
    ...
  ]
}'
```




**Example: Upload a referenced file in Observation$observation-create**

```bash
curl 'https://api.redoxengine.com/fhir/R4/{{DESTINATION-SLUG}}/{{ENVIRONMENT-FLAG}}/Observation/$observation-create' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'Content-Type: application/fhir+json' \
--data '{
  "resourceType": "Bundle",
  ...
  "entry": [
    {
      "resource": {
        "eventUri": "https://fhir.redoxengine.com/EventDefinition/DiagnosticReportCreate",
        "resourceType": "MessageHeader",
        ...
        "extension": [
          {
             "url": "http://hl7.org/fhir/5.0/StructureDefinition/extension-Observation.valueAttachment",
             "valueAttachment": {
               "contentType": "application/pdf",
               "title": "Lab Result",
               "url": "https://blob.redoxengine.com/123456789"
               }
          }
        ]
      }
    },
    ...
  ]
}'
```


6. Populate the rest of the message as needed, then send 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 <u>Process</u> tab of the log. 

## Embed a file

You can embed a file in any FHIR resource containing a FHIR `Attachment` datatype. [Learn more about FHIR Attachment](https://hl7.org/fhir/r4/datatypes.html#attachment). 

You can embed a PDF with results and vitals directly in the `DiagnosticReport` or `Observation` resources, so long as the file fits within the size limit for the type of traffic. [Check limits by traffic type](https://docs.redoxengine.com/permalink/6KOwEzjE4jb2DBnQf6PBky/#message-and-file-size-limits).

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](/api-reference/redox-data-model-api/authenticate-an-oauth-api-key). 
3. Use the FHIR operation you want for sending results or vitals (`$diagnosticreport-create`, `$observation-create`).
4. Populate the required document fields to include the encoded file in your request: 
   - Replace `{{ENVIRONMENT-FLAG}}` with `Development`, `Staging`, or `Production`.
   - Replace `$API_TOKEN` with your access token. 
   - Replace `{{DESTINATION-SLUG}}` with the human-readable safe name for the intended destination.  
5. Populate the `entry.resource.presentedForm` fields to include the encoded file: 
   - In the `contentType` field, enter a **valid MIME type**. [Learn more about MIME types for files](https://docs.w3cub.com/http/basics_of_http/mime_types).
   - In the `data` field, insert the **base64 encoded string** for the file. 


**Example: Embed a file in DiagnosticReport$diagnosticreport-create**

```bash
curl 'https://api.redoxengine.com/fhir/R4/{{DESTINATION-SLUG}}/{{ENVIRONMENT-FLAG}}/DiagnosticReport/$diagnosticreport-create' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'Content-Type: application/fhir+json' \
--data '{
  "resourceType": "Bundle",
  ...
  "entry": [
    {
      "resource": {
        "eventUri": "https://fhir.redoxengine.com/EventDefinition/DiagnosticReportCreate",
        "resourceType": "MessageHeader",
        ...
        "resource": {
          "resourceType": "DiagnosticReport",
          "presentedForm": [
            {
              "contentType": "application/pdf",
              "title": "Lab Results",
              "data": "XG82ZSC0aHUgd3F5IHlvdSBsaYU="
            }
          }
        ]
      }
    },
    ...
  ]
}'
```




**Example: Embed a file in Observation$observation-create**

```bash
curl 'https://api.redoxengine.com/fhir/R4/{{DESTINATION-SLUG}}/{{ENVIRONMENT-FLAG}}/Observation/$observation-create' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'Content-Type: application/fhir+json' \
--data '{
  "resourceType": "Bundle",
  ...
  "entry": [
    {
      "resource": {
        "eventUri": "https://fhir.redoxengine.com/EventDefinition/DiagnosticReportCreate",
        "resourceType": "MessageHeader",
        ...
        "extension": [
          {
             "url": "http://hl7.org/fhir/5.0/StructureDefinition/extension-Observation.valueAttachment",
             "valueAttachment": {
               "contentType": "application/pdf",
               "title": "Lab Result",
               "data": "XG82ZSC0aHUgd3F5IHlvdSBsaYU="
               }
          }
        ]
      }
    },
    ...
  ]
}'
```


6. Populate the rest of the message as needed, then send to your connection’s EHR system.
7. 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.