Transferring Files

The Media, Notes, and Results data models allow for the transfer of files via the Redox API.

There are two ways to send files, depending on the expected file size:

  • Files up to 10mb can be inserted directly into a request payload as a base64 encoded string
  • Files up to 30mb can be uploaded separately before sending and referenced within the request

In either case, the destination system will receive the request in the same way – as a base64 encoded string within the request payload.

If you attempt to embed a file that is too large, you will receive a 413 from Redox.

Sending Embedded Files

Files up to 10mb can be directly embedded within Media, Results, or Notes requests as base64 encoded strings.

Media Files

Include the base64 encoded file in the Media.FileContents field and include an accurate Media.FileType.

{
   …
   "Media": {
     "FileType": "PDF",
     "FileName": "SamplePDF",
     "FileContents": "",
     …
   }
 }

Results Files

Include the base64 encoded file in the Orders[].Results[].Value property, and set Orders[].Results[].ValueType to “Encapsulated Data”.

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

Notes Files

Include the base64 encoded file in the Note.FileContents property, and set Note.ContentType to “Base64 Encoded”.

{ 
   …
   "Note": {
     "ContentType": "Base64 Encoded",
     "FileName": "SamplePDF-Order Specific Note",
     "FileContents": "",
   …
 }

For full data model specifications, including allowed property values, see the data model docs directly: https://developer.redoxengine.com/data-models

Uploading and Sending Files up to 30mb

To send files up to 30mb, you’ll need to upload them to Redox first before sending.

Once you’ve uploaded a file, you will be able to send a request via Redox API with a reference to the uploaded file in place of the file itself. Redox will replace the reference with a base64 encoded string before it is sent along to the intended destination.

1) Upload the file to Redox

The first step is to upload your file via the Redox upload endpoint:

POST https://blob.redoxengine.com/upload

This endpoint utilizes the same source authentication as a normal Redox API request, as detailed here: Initiating Requests (Source)

cURL Upload Example

curl https://blob.redoxengine.com/upload \
  -H "Authorization: Bearer " -X POST \
  -F [email protected]

Response

If your upload is successful, you’ll receive a 201 response with the following payload body:

{
   "URI": "https://blob.redoxengine.com/123456789"
}

The returned file URI is the reference to your uploaded file that you need for the next step.

2) Include the file reference within your request

Sending an uploaded file is nearly the same process as that of an embedded file described above. Simply include the URI from step one in place of the base64 encoded file within the request.

Example

{ 
   …
   "FileContents": "https://blob.redoxengine.com/123456789",
   …
 }

Redox will replace the URI with the base64 encoded file string before the request is sent to your intended destination(s), such that the destination system will always receive the payload with a base64 encoded string regardless of its size or how it was sent.