# 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 describes how to send a generic file with the <u>**Redox FHIR API**</u>. If you want to send results-related documents, [learn how to send results or vitals](/how-to-use-redox/send-results-or-vitals-via-the-redox-fhir-api).

## 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

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.

## Prerequisites

- 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 <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 `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](/api-reference/redox-data-model-api/authenticate-an-oauth-api-key). 
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. 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` 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](/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'
```


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
{
   "location": "https://blob.redoxengine.com/123456789"
}

```


5. Reference the uploaded file in a `DocumentReference$documentreference-create` request to your connection. [Refer to the DocumentReference schema](https://docs.redoxengine.com/permalink/99e94927-8ac9-55e0-aa05-a1c6dc20d58d-$documentreference-create) 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](https://docs.w3cub.com/http/basics_of_http/mime_types).
     - (Optional) In the `title` field, enter the **name of the file**. 

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

```bash
curl 'https://api.redoxengine.com/fhir/R4/{{DESTINATION-SLUG}}/{{ENVIRONMENT-FLAG}}/DocumentReference/$documentreference-create' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'Content-Type: application/fhir+json' \
--data '{
  "resourceType": "Bundle",
  ...
  "entry": [
    ...
    {
      ...
      "resource": {
        "resourceType": "DocumentReference",
        ...
        "content": [
          {
            "attachment": {
              "contentType": "application/pdf",
              "title": "Order Request",
              "url": "https://blob.redoxengine.com/123456789"
            }
          }
        ]
      }
    },
    ...
  ]
}'
```




> **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](https://docs.redoxengine.com/permalink/99e94927-8ac9-55e0-aa05-a1c6dc20d58d-$documentreference-create).


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 <u>Process</u> tab of the log. 

## Embed a file

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](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. Embed the uploaded file in a `DocumentReference$documentreference-create` request to your connection. [Refer to the DocumentReference schema](https://docs.redoxengine.com/permalink/99e94927-8ac9-55e0-aa05-a1c6dc20d58d-$documentreference-create) 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](/basics/data-exchange-with-redox/Managing-source-details-in-outgoing-requests).
   - 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](https://docs.w3cub.com/http/basics_of_http/mime_types).
     - 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
curl 'https://api.redoxengine.com/fhir/R4/{{DESTINATION-SLUG}}/{{ENVIRONMENT-FLAG}}/DocumentReference/$documentreference-create' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'Content-Type: application/fhir+json' \
--data '{
  "resourceType": "Bundle",
  ...
  "entry": [
    ...
    {
      ...
      "resource": {
        "resourceType": "DocumentReference",
        ...
        "content": [
          {
            "attachment": {
              "contentType": "application/pdf",
              "title": "Order Request",
              "data": "XG82ZSC0aHUgd3F5IHlvdSBsaYU="
            }
          }
        ]
      }
    },
    ...
  ]
}'
```




> **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](https://docs.redoxengine.com/permalink/99e94927-8ac9-55e0-aa05-a1c6dc20d58d-$documentreference-create).


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.