---
title: 'DocumentReference (FHIR R4)'
description: 'FHIR R4 DocumentReference resource.'
nav: 'API / R4 / DocumentReference'
order: 110
version: v1
fhir: r4
source: generated
updated: '2026-09-23'
---

# DocumentReference (FHIR R4)

<FhirResourceHeader fhir="r4" slug="documentreference" />

FHIR R4 DocumentReference resource.

> This reference is generated from the canonical Huli Public API OpenAPI specification and the server's FHIR R4 CapabilityStatement — do not edit it directly.

## FHIR R4 Specification

Official spec: [DocumentReference — HL7 FHIR R4](https://hl7.org/fhir/R4/documentreference.html)

## Supported Interactions

- **read** — Read a single resource by ID (`GET /fhir/R4/{Resource}/{id}`)
- **search-type** — Search resources with query parameters (`GET /fhir/R4/{Resource}?...`)
- **create** — Create a new resource (`POST /fhir/R4/{Resource}`)
- **update** — Update an existing resource (`PUT /fhir/R4/{Resource}/{id}`)
- **$upload** — operation

## Scopes

Scopes are shared across FHIR releases — the same `system/DocumentReference.*` scope grants DocumentReference access on both `/fhir/R4` and `/fhir/R5`.

- <Scope name="system/DocumentReference.rs" /> — see [scope reference](/v1/scopes#system-documentreference-rs)
- <Scope name="system/DocumentReference.cru" /> — see [scope reference](/v1/scopes#system-documentreference-cru)

## Search Parameters

| Parameter | Type | Notes |
|-----------|------|-------|
| `patient` | reference | Resource reference — supply the UUID of the referenced resource. |
| `type` | token | Exact match. For identifiers use `system|value` format. |
| `category` | token | Exact match. For identifiers use `system|value` format. |
| `date` | date | Supports FHIR date prefixes: `eq`, `ne`, `gt`, `ge`, `lt`, `le`. Format: `[prefix]YYYY-MM-DD`. |
| `_count` | number | Integer. For `_count`: default 20, max 100. |
| `_cursor` | string | Case-insensitive partial match. |

## Endpoints

### Read DocumentReference

Retrieve a single DocumentReference. The binary is referenced via a 30-minute signed URL in content[0].attachment.url (never inlined).

<Endpoint method="GET" path="/fhir/R4/DocumentReference/{id}" />

**Required scope:** <Scope name="system/DocumentReference.rs" />

#### Code Samples

:::CodeGroup

```bash {label="cURL"}
TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/DocumentReference.rs" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/fhir/R4/DocumentReference/${RESOURCE_ID} \
  -H "Authorization: Bearer ${TOKEN}"
```

```typescript {label="TypeScript"}
const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/DocumentReference/${id}`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${token}`,
    },

  }
);

if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();
```

```python {label="Python"}
import os
import requests

token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}"}

resp = requests.get(
    f"https://api.huli.ai/fhir/R4/DocumentReference/{resource_id}",
    headers=headers,
)
resp.raise_for_status()
print(resp.json())
```

```java {label="Java"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class getDocumentReferenceExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");
        String resourceId = "RESOURCE_ID";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/DocumentReference/" + resourceId))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

        HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("status: " + response.statusCode());
        System.out.println(response.body());
    }
}
```

```go {label="Go"}
import (
    "fmt"
    "net/http"
    "os"
)

func getDocumentReferenceExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/DocumentReference/"+resourceID+"", nil)
    req.Header.Set("Authorization", "Bearer "+token)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}
```

:::

#### Errors

| Code | Status | Description |
|------|--------|-------------|
| [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed |
| [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope |
| [HPB-00102](/v1/errors#hpb-00102) | 404 | Resource not found |
| [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded |

---

### Update DocumentReference metadata

Update mutable metadata (category, description) of a DocumentReference. The binary content is
immutable on this surface. Set `status: entered-in-error` to soft-delete the document.

<Endpoint method="PUT" path="/fhir/R4/DocumentReference/{id}" />

**Required scope:** <Scope name="system/DocumentReference.u" />

#### Code Samples

:::CodeGroup

```bash {label="cURL"}
TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/DocumentReference.u" \
  | jq -r .access_token)

curl -X PUT https://api.huli.ai/fhir/R4/DocumentReference/${RESOURCE_ID} \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/fhir+json" \
  -d @resource.json
```

```typescript {label="TypeScript"}
const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/DocumentReference/${id}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/fhir+json",
    },
    body: JSON.stringify(payload),
  }
);

if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();
```

```python {label="Python"}
import os
import requests

token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/fhir+json"}

resp = requests.put(
    f"https://api.huli.ai/fhir/R4/DocumentReference/{resource_id}",
    headers=headers,
    json=payload,
)
resp.raise_for_status()
print(resp.json())
```

```java {label="Java"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class updateDocumentReferenceExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");
        String resourceId = "RESOURCE_ID";
        String payload = "{}"; // your serialized FHIR resource

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/DocumentReference/" + resourceId))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .header("Content-Type", "application/fhir+json")
        .method("PUT", HttpRequest.BodyPublishers.ofString(payload))
        .build();

        HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("status: " + response.statusCode());
        System.out.println(response.body());
    }
}
```

```go {label="Go"}
import (
    "fmt"
    "net/http"
    "os"
)

func updateDocumentReferenceExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("PUT", "https://api.huli.ai/fhir/R4/DocumentReference/"+resourceID+"", body)
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/fhir+json")
    // set req.Body to your serialized resource
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}
```

:::

#### Errors

| Code | Status | Description |
|------|--------|-------------|
| [HPB-00101](/v1/errors#hpb-00101) | 400 | Validation error |
| [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed |
| [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope |
| [HPB-00102](/v1/errors#hpb-00102) | 404 | Resource not found |
| [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded |

---

### Search DocumentReferences

Search DocumentReferences for a patient (the `patient` parameter is required). Filter by
`category`, `type`, and `date`. Paginated with `_count` and `_cursor`. Search
results do not carry a signed URL — read the individual resource for the binary.

<Endpoint method="GET" path="/fhir/R4/DocumentReference" />

**Required scope:** <Scope name="system/DocumentReference.rs" />

#### Query Parameters

<ParamTable :rows='[{&quot;name&quot;:&quot;patient&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:true,&quot;description&quot;:&quot;Patient reference (UUID). Required.&quot;},{&quot;name&quot;:&quot;category&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Document category token.&quot;},{&quot;name&quot;:&quot;type&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Document type token (LOINC code).&quot;},{&quot;name&quot;:&quot;date&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Document date (FHIR date, prefix-aware).&quot;},{&quot;name&quot;:&quot;_count&quot;,&quot;type&quot;:&quot;integer&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Number of results per page (default: 20, max: 100).&quot;},{&quot;name&quot;:&quot;_cursor&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Opaque pagination cursor from the `next` link of a previous search result.&quot;}]' />

#### Code Samples

:::CodeGroup

```bash {label="cURL"}
TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/DocumentReference.rs" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/fhir/R4/DocumentReference \
  -H "Authorization: Bearer ${TOKEN}"
```

```typescript {label="TypeScript"}
const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/DocumentReference`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${token}`,
    },

  }
);

if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();
```

```python {label="Python"}
import os
import requests

token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}"}

resp = requests.get(
    f"https://api.huli.ai/fhir/R4/DocumentReference",
    headers=headers,
)
resp.raise_for_status()
print(resp.json())
```

```java {label="Java"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class searchDocumentReferencesExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/DocumentReference"))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

        HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("status: " + response.statusCode());
        System.out.println(response.body());
    }
}
```

```go {label="Go"}
import (
    "fmt"
    "net/http"
    "os"
)

func searchDocumentReferencesExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/DocumentReference", nil)
    req.Header.Set("Authorization", "Bearer "+token)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}
```

:::

#### Errors

| Code | Status | Description |
|------|--------|-------------|
| [HPB-00101](/v1/errors#hpb-00101) | 400 | Validation error |
| [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed |
| [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope |
| [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded |

---

### Create DocumentReference (inline upload)

Create a DocumentReference by inlining the binary as base64 in
content[0].attachment.data (with a filename in attachment.title). Equivalent to the
$upload operation's inline mode. Enforces the 25 MB ceiling and magic-byte content
validation (PDF/JPEG/PNG/WEBP/DICOM).

<Endpoint method="POST" path="/fhir/R4/DocumentReference" />

**Required scope:** <Scope name="system/DocumentReference.c" />

#### Code Samples

:::CodeGroup

```bash {label="cURL"}
TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/DocumentReference.c" \
  | jq -r .access_token)

curl -X POST https://api.huli.ai/fhir/R4/DocumentReference \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/fhir+json" \
  -d @documentreference.json
```

```typescript {label="TypeScript"}
const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/DocumentReference`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/fhir+json",
    },
    body: JSON.stringify(payload),
  }
);

if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();
```

```python {label="Python"}
import os
import requests

token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/fhir+json"}

resp = requests.post(
    f"https://api.huli.ai/fhir/R4/DocumentReference",
    headers=headers,
    json=payload,
)
resp.raise_for_status()
print(resp.json())
```

```java {label="Java"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class createDocumentReferenceExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");
        String payload = "{}"; // your serialized FHIR resource

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/DocumentReference"))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .header("Content-Type", "application/fhir+json")
        .method("POST", HttpRequest.BodyPublishers.ofString(payload))
        .build();

        HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("status: " + response.statusCode());
        System.out.println(response.body());
    }
}
```

```go {label="Go"}
import (
    "fmt"
    "net/http"
    "os"
)

func createDocumentReferenceExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("POST", "https://api.huli.ai/fhir/R4/DocumentReference", body)
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/fhir+json")
    // set req.Body to your serialized resource
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}
```

:::

#### Errors

| Code | Status | Description |
|------|--------|-------------|
| [HPB-00101](/v1/errors#hpb-00101) | 400 | Validation error |
| [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed |
| [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope |
| [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded |

---

### Upload a document ($upload)

Upload a document binary in one of two modes: (1) multipart/form-data with a `file` part
plus a `subject` (Patient reference or UUID) and optional `encounter` field; or (2) a JSON
DocumentReference with content[0].attachment.data base64 (identical to POST
/DocumentReference). Enforces the 25 MB ceiling, magic-byte content validation, and
SHA-256 dedup.

<Endpoint method="POST" path="/fhir/R4/DocumentReference/$upload" />

**Required scope:** <Scope name="system/DocumentReference.c" />

#### Request Body

<ParamTable :rows='[{&quot;name&quot;:&quot;file&quot;,&quot;type&quot;:&quot;string(binary)&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;&quot;},{&quot;name&quot;:&quot;subject&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;&quot;},{&quot;name&quot;:&quot;encounter&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;&quot;}]' />

#### Code Samples

:::CodeGroup

```bash {label="cURL"}
TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/DocumentReference.c" \
  | jq -r .access_token)

curl -X POST https://api.huli.ai/fhir/R4/DocumentReference/$upload \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/fhir+json" \
  -d @$upload.json
```

```typescript {label="TypeScript"}
const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/DocumentReference/$upload`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/fhir+json",
    },
    body: JSON.stringify(payload),
  }
);

if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();
```

```python {label="Python"}
import os
import requests

token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/fhir+json"}

resp = requests.post(
    f"https://api.huli.ai/fhir/R4/DocumentReference/$upload",
    headers=headers,
    json=payload,
)
resp.raise_for_status()
print(resp.json())
```

```java {label="Java"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class uploadDocumentReferenceExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");
        String payload = "{}"; // your serialized FHIR resource

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/DocumentReference/$upload"))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .header("Content-Type", "application/fhir+json")
        .method("POST", HttpRequest.BodyPublishers.ofString(payload))
        .build();

        HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("status: " + response.statusCode());
        System.out.println(response.body());
    }
}
```

```go {label="Go"}
import (
    "fmt"
    "net/http"
    "os"
)

func uploadDocumentReferenceExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("POST", "https://api.huli.ai/fhir/R4/DocumentReference/$upload", body)
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/fhir+json")
    // set req.Body to your serialized resource
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}
```

:::

#### Errors

| Code | Status | Description |
|------|--------|-------------|
| [HPB-00101](/v1/errors#hpb-00101) | 400 | Validation error |
| [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed |
| [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope |
| [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded |

---