$purge

Available since version 2602.

The $purge operation permanently deletes a Patient resource and all resources in that patient's compartment, including all historical versions.

This operation implements the FHIR Patient Purge specification. By default, this operation uses the system default compartment for Patient, or a custom compartment can be passed as a parameter.

Idempotent: Purging a non-existent patient returns 200 (sync) or 202 (async) without error. This allows re-running $purge after a partial failure.

After purge: Purged resources are permanently removed. Requests to read them return 404 Not Found (not 410 Gone), since the resources no longer exist.

Scoped references: Only resources that reference the patient with the full reference format (e.g., Patient/<id>) are deleted. Resources referencing a different resource type with the same ID are not affected.

Audit logging: A successful purge creates an AuditEvent with action: "E" (Execute) and subtype: "$purge". See How to configure audit log for setup instructions.

Endpoint

POST /fhir/Patient/<patient-id>/$purge

Parameters

The request body is optional. When provided, it must be a FHIR Parameters resource (e.g. {"resourceType": "Parameters"}). An empty JSON body {} is rejected with 422 and "Request body must be a Parameters resource". Omit the body or send {"resourceType": "Parameters"} when no custom parameters are needed.

Optional parameter:

Parameter	Type	Description
`compartmentDefinition`	resource (CompartmentDefinition)	A contained `CompartmentDefinition` resource that defines which resource types and search parameters to use for identifying compartment resources. If omitted, the standard server Patient CompartmentDefinition is used.

Async mode

To run the purge asynchronously, include the Prefer: respond-async header. In async mode, the Patient is deleted immediately, while compartment resources are deleted in background tasks. The response includes a Content-Location header with a URL to check the operation status.

The number of concurrent async worker threads is controlled by the BOX_SCHEDULER_EXECUTORS setting (default: 4).

Basic usage

Send a POST request to purge a patient and all associated resources:

POST /fhir/Patient/pt-1/$purge
Content-Type: application/json

Status

200 OK

Body

{
  "resourceType": "OperationOutcome",
  "id": "informational",
  "issue": [
    {
      "severity": "fatal",
      "code": "informational",
      "diagnostics": "All resources for Patient/pt-1 were purged"
    }
  ]
}

After the operation completes, the Patient and all resources referencing it (Observations, Conditions, Encounters, etc.) are permanently removed, including their history.

Async mode

POST /fhir/Patient/pt-1/$purge
Content-Type: application/json
Prefer: respond-async

Status

202 Accepted

Headers

Content-Location — URL to check purge status (e.g. /fhir/$async/<operation-id>)

Body

{
  "resourceType": "OperationOutcome",
  "id": "informational",
  "issue": [
    {
      "severity": "fatal",
      "code": "informational",
      "diagnostics": "Purge for Patient/pt-1 accepted for async processing"
    }
  ]
}

Check async status

Query the status URL from the Content-Location header:

GET /fhir/$async/<operation-id>

Status

202 Accepted

Status

200 OK

Body

{
  "resourceType": "Bundle",
  "type": "batch-response",
  "entry": [
    {
      "response": {
        "status": "200 OK",
        "outcome": {
          "resourceType": "OperationOutcome",
          "id": "informational",
          "issue": [
            {
              "severity": "fatal",
              "code": "informational",
              "diagnostics": "Operation completed successfully"
            }
          ]
        }
      }
    }
  ]
}

Cancel async operation

To cancel an active async purge, send a DELETE request to the status URL:

DELETE /fhir/$async/<operation-id>

Status

202 Accepted

Custom compartment definition

By default, $purge uses the standard server Patient CompartmentDefinition. You can provide a custom compartment definition to control exactly which resource types are purged.

For example, to purge only Observations associated with the patient:

POST /fhir/Patient/pt-1/$purge
Content-Type: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "compartmentDefinition",
      "resource": {
        "resourceType": "CompartmentDefinition",
        "url": "http://example.com/custom-compartment",
        "name": "CustomPatientCompartment",
        "code": "Patient",
        "status": "active",
        "search": true,
        "resource": [
          {
            "code": "Observation",
            "param": ["subject"]
          }
        ]
      }
    }
  ]
}

Status

200 OK

Body

{
  "resourceType": "OperationOutcome",
  "id": "informational",
  "issue": [
    {
      "severity": "fatal",
      "code": "informational",
      "diagnostics": "All resources for Patient/pt-1 were purged"
    }
  ]
}

Only Observation resources referencing this patient are deleted. Other resource types (Conditions, Encounters, etc.) are left intact.

The custom CompartmentDefinition must satisfy:

code must be Patient
Must have at least one resource entry with a non-empty param list