# Send a file via Redox Data Model 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 file with the <u>**Redox Data Model API**</u>. 

## 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 data model to use

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

- The `Notes` data model is for 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). This data model sends files as plain or rich text, so the content is subject to each EHR system's rendering capabilities. In case the EHR system has search or natural language processing (NLP) capabilities, `Notes` may offer superior search and usability.


> **What to send with a Notes file**
>
> With the `Notes` data model, EHR systems typically require that you provide the patient identifier and basic demographic information (e.g., name, date of birth). 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 is for a patient’s test results or lab-related data. 
- The `Media` data model is for PDFs, images, or audio. However, most EHR systems don't support the `Media` data model for diagnostic quality images, and DICOM files typically exceed the size limits for `Media`. We recommend using `Notes` over `Media`.

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](https://docs.redoxengine.com/permalink/data-model-landing-page) for full specs.

## Prerequisites

- Decide which sending method to use (i.e., upload or embed a file).
- Decide which Redox data model to use (`Notes`, `Results`,  `Media`).
- _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 blob. Then, include a reference to the file in your request.

1. Locate the file you want to upload.
2. Authenticate an OAuth API key like you would for any Data Model API request. [Learn how to authenticate and initiate a request](/api-reference/redox-data-model-api/authenticate-an-oauth-api-key). 
3. Send an HTTP request with your file to the Redox blob. The file should be uploaded with the `file` key, using the `multipart/form-data` content type. [Learn more about multipart form submission](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/POST#multipart_form_submission).
   - The `Redox-source-Id` header is only required if you have multiple sources and you’re using an OAuth API key.  Even though it’s a FHIR header, it’s still supported for this scenario with the Data Model API. [Learn about managing source details](/basics/data-exchange-with-redox/Managing-source-details-in-outgoing-requests). 


**Example: Upload a file to Redox with the Data Model API**

```bash
curl https://blob.redoxengine.com/upload \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Redox-source-Id: {{SOURCE-ID}}" \
  -X POST \
  -F file=@file.pdf
```



**Example: Upload a file with the Redox Data Model API (Node.js)**

```javascript
const fs = require('fs');

fs.openAsBlob('file.pdf')
.then((blob) => {
  const body = new FormData();
  body.append('file', blob)
  return fetch('https://blob.redoxengine.com/upload', {
    method: 'POST',
    headers: {
      'Redox-Source-Id': '{{SOURCE-ID}}',
      'Authorization': 'Bearer $API_TOKEN'
    },
    body
  })
})
.then((resp) => {
  return resp.json()
}) 
.then((body) =>
  console.log("blobfile URL:", body.URI)
)
```


4. If successful, you receive a `201 Created` status with the URI reference to your file in the body of the response.
5. Send the uploaded file following the same instructions for embedding a file in the relevant data model below. In place of the base64 encoded string, include the URI from the previous step.
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 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).

The instructions for populating the request below are also used for uploading and referencing a file, except the URI is used instead of the base64 encoded string in all cases.  

### Embed a file in the Notes data model

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](https://docs.redoxengine.com/permalink/notes-new) for all the available fields.

**Example: Embed a file in the Notes data model**

```json
{ 
   …
   "Note": {
     "ContentType": "Base64 Encoded",
     "FileContents": "XG82ZSC0aHUgd3F5IHlvdSBsaYU=",
     "FileName": "Order Specific Note",
     "DocumentType": "Clinical Note", 
     "DocumentID": "b169267c-10c9-4fe3-91ae-9ckf5703e90l", 
     "Provider": {
       “ID”: "4356789876",  
       …
       }
   …
 }

```



### Embed a file in the Results data model

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](https://docs.redoxengine.com/permalink/results-new) for all the available fields.

**Example: Embed a file in the Results data model**

```json
{
   …
   "Orders": [
     { …
       "Results": [
         { 
           "Value": "XG82ZSC0aHUgd3F5IHlvdSBsaYU=",
           "ValueType": "Encapsulated Data",
           "FileType": "PDF",
            …
         }
      ]
     }
   ]
}

```



### Embed a file in the Media data model

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](https://docs.redoxengine.com/permalink/media-new) for all the available fields.

**Example: Embed a file in the Media data model**

```json
{   …
   "Media": {
     "FileType": "PDF",
     "FileName": "Annual visit",
     "FileContents": "XG82ZSC0aHUgd3F5IHlvdSBsaYU=",
	   "DocumentType": "Consent form",  
     "DocumentID": "b169267c-10c9-4fe3-91ae-9ckf5703e90l",     
     "Provider": {
        “ID”: "4356789876",  
        …
        }
     "Availability": "Available",
    …
    }
 }
```