Helix AU Core - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Binaries

Process

Uploading a DocumentReference to the FHIR server involves a two-step process.

• Create the intended DocumentReference with a placeholder attachment.
• Use the ID of the created DocumentReference and initiate the Binary Access Write Operation to upload the binary content.

​

Binary Access Write Operation

Here is an example of creating a DocumentReference and uploading binary content.

POST /DocumentReference
Content-Type: application/fhir+json

{
  "resourceType": "DocumentReference",
	"subject": {
		"reference": "Patient/123"
	},
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf"
      }
    }
  ]
}

Upon creation of the DocumentReference, the server responds with a location header and details of the created resource, including the assigned ID.

Location: https://r4.helix.medicaldirector.com/Tenant1/DocumentReference/c6294fe3-177c-465e-a683-5c03b13bf920/_history/1

{
    "resourceType": "DocumentReference",
    "id": "c6294fe3-177c-465e-a683-5c03b13bf920" // generated ID by the server,
    "meta": {
    "versionId": "1",
    "lastUpdated": "2025-09-08T12:34:56Z"
  },
  "subject": {
    "reference": "Patient/123"
  },
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf"
      }
    }
  ]
}

The obtained ID is required for the following Binary Access Write Operation. The path parameter specifies a FHIR Path expression to the attachment element within the DocumentReference resource. The Content-Type header in the HTTP request determines the content type of the attachment.

Note: This value is not validated against the placeholder resource and the existing value will be overwritten.

POST /DocumentReference/c6294fe3-177c-465e-a683-5c03b13bf920/$binary-access-write?path=DocumentReference.content.attachment
Content-Type: application/pdf

(... binary content ...)

Binary Access Read Operation

The Binary Access Read Operation facilitates the retrieval of binary content from attachment elements, following the same approach used in the previous write operation.

You can find detailed process at Helix Blob URLs.