Delete Resource

Marks a resource as deleted. Most servers use soft delete, preserving the resource in history.

Endpoint

DELETE /fhir/{resourceType}/{id}

resourceType

string

required

The FHIR resource type (e.g., Patient, Observation, Encounter)

string

required

The logical ID of the resource to delete

Headers

Prefer

string

Response style:

return=representation - Return OperationOutcome
return=minimal (default) - No response body
return=OperationOutcome - Return OperationOutcome

Query Parameters

search parameters

string

For conditional delete. Delete the resource matching these search parameters.Example: ?identifier=http://hospital.example/mrn|12345

Response

204 No Content

Resource deleted successfully. No response body.

Headers:

200 OK

Resource deleted successfully with OperationOutcome (when using Prefer: return=OperationOutcome).

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "Resource Patient/123 deleted successfully"
    }
  ]
}

404 Not Found

Resource doesn’t exist (some servers return 204 for idempotency).

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "diagnostics": "Resource Patient/123 not found"
    }
  ]
}

409 Conflict

Resource cannot be deleted due to referential integrity or business rules.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "conflict",
      "diagnostics": "Cannot delete Patient/123: referenced by Observation/456, Encounter/789"
    }
  ]
}

412 Precondition Failed

Conditional delete matched multiple resources (ambiguous).

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "multiple-matches",
      "diagnostics": "Multiple resources match search criteria. Conditional delete requires exactly one match."
    }
  ]
}

Examples

curl -X DELETE "https://your-server.com/fhir/Patient/123"

Delete Behavior

Soft Delete (Typical)

Most FHIR servers use soft delete:

Resource marked as deleted in database
History preserved and accessible
GET /Patient/123 returns 410 Gone
GET /Patient/123/_history/5 still works (returns version 5)

Hard Delete (Rare)

Complete removal from database:

Resource and all history permanently deleted
Cannot be recovered
Usually restricted by policy or disabled entirely

Check Server Behavior: Review the server’s CapabilityStatement or documentation to understand its delete behavior.

Idempotent Delete

DELETE is idempotent - deleting an already-deleted resource succeeds:

# First delete
DELETE /fhir/Patient/123  # 204 No Content

# Second delete (same resource)
DELETE /fhir/Patient/123  # 204 No Content (idempotent)

# Reading the deleted resource
GET /fhir/Patient/123     # 410 Gone

Conditional Delete

Delete by search criteria instead of ID:

DELETE /fhir/{resourceType}?{search_parameters}

Behavior:

0 matches: No-op, returns 204 No Content
1 match: Deletes that resource → 204 No Content
2+ matches: Rejects as ambiguous → 412 Precondition Failed

Example: Delete patient by identifier

DELETE /fhir/Patient?identifier=http://hospital.example/mrn|12345

Accessing Deleted Resources

After soft delete, use history endpoints to access deleted resources:

# List all versions (including deleted)
GET /fhir/Patient/123/_history

# Read specific version (even if resource is deleted)
GET /fhir/Patient/123/_history/5

Referential Integrity

Some servers check if other resources reference the resource being deleted: Protected Resources (common scenarios):

Patient referenced by Observations, Encounters
Practitioner referenced by many resources
Organization referenced by locations, departments

Server Behavior:

Allow deletion regardless (most permissive)
Return 409 Conflict if references exist (most cautious)
Cascade delete (rare - delete referencing resources too)

Common Use Cases

Delete Test Data

DELETE /fhir/Patient/test-patient-123

Soft Delete with Verification

import requests

# Delete
requests.delete('https://server.com/fhir/Patient/123')

# Verify it's gone (should get 410)
response = requests.get('https://server.com/fhir/Patient/123')
assert response.status_code == 410, "Resource should be deleted"

Conditional Delete by Identifier

DELETE /fhir/Patient?identifier=http://hospital.example/temp|temp-12345

Delete with Audit Trail

import requests

patient_id = "123"
url = f"https://server.com/fhir/Patient/{patient_id}"

# Get current state before deleting (for audit)
patient = requests.get(url).json()
audit_log = {
    "action": "delete",
    "resource": patient,
    "timestamp": "2026-01-12T15:00:00Z"
}

# Perform delete
response = requests.delete(url)
if response.status_code == 204:
    print("Deleted and logged")

Best Practices

Cannot Undo: Even with soft delete, most UIs don’t provide “undelete” functionality. Ensure deletion is intended before proceeding.

Check References First: Before deleting, search for resources that reference it to avoid breaking referential integrity:

GET /fhir/Observation?subject=Patient/123
GET /fhir/Encounter?subject=Patient/123

If any exist, consider whether deletion is appropriate.

Empty Body: DELETE requests should have an empty body per FHIR specification. Don’t send a resource in the body.

Resource History

View deleted resource versions

Search

Find resources before deleting

Update Resource

Modify instead of deleting

Learn FHIR CRUD

Understand FHIR delete semantics

Authorizations

Authorization

string

header

required

Bearer token authentication

Path Parameters

resourceType

string

required

The FHIR resource type (e.g., Patient, Observation, Encounter)

string

required

The logical ID of the resource

Response

Resource deleted

A FHIR resource. All resources have resourceType, id, and meta fields.

resourceType

string

required

The type of resource

string

Logical id of this artifact

​Endpoint

​Headers

​Query Parameters

​Response

​204 No Content

​200 OK

​404 Not Found

​409 Conflict

​412 Precondition Failed

​Examples

​Delete Behavior

​Soft Delete (Typical)

​Hard Delete (Rare)

​Idempotent Delete

​Conditional Delete

​Accessing Deleted Resources

​Referential Integrity

​Common Use Cases

​Delete Test Data

​Soft Delete with Verification

​Conditional Delete by Identifier

​Delete with Audit Trail

​Best Practices

​See Also

Resource History

Search

Update Resource

Learn FHIR CRUD

Authorizations

Path Parameters

Response

Endpoint

Headers

Query Parameters

Response

204 No Content

200 OK

404 Not Found

409 Conflict

412 Precondition Failed

Examples

Delete Behavior

Soft Delete (Typical)

Hard Delete (Rare)

Idempotent Delete

Conditional Delete

Accessing Deleted Resources

Referential Integrity

Common Use Cases

Delete Test Data

Soft Delete with Verification

Conditional Delete by Identifier

Delete with Audit Trail

Best Practices

See Also