Deleting a FHIR resource

The FHIR delete interaction removes an existing FHIR resource from a HealthLake data store. For additional information, see delete in the FHIR R4 RESTful API documentation.

To delete a FHIR resource

Deleting FHIR resources based on conditions

Conditional delete is particularly useful when you don't know the specific FHIR resource ID but have other identifying information about the resource you want to delete.

Conditional delete allows you to delete an existing resource based on search criteria rather than by logical FHIR ID. When the server processes the delete request, it performs a search using standard search capabilities for the resource type to resolve a single logical ID for the request.

How conditional delete works

The server's action depends on how many matches it finds:

Response scenarios

AWS HealthLake handles conditional delete operations with the following response patterns:

Successful Operations

ID-Based Conditional Delete

When performing conditional delete based on id with additional parameters (createdAt, _tag, or _lastUpdated):

Non-ID-Based Conditional Delete

When id is not provided or when using parameters other than createdAt, _tag, or _lastUpdated:

Conflict Situations

Several scenarios result in 412 Precondition Failed responses:

Example of a Successful Conditional Delete

The following example deletes a Patient resource based on specific criteria:

DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?name=peter&birthdate=2000-01-01&phone=1234567890

This request deletes a Patient resource where:

Best Practices

Deleting multiple FHIR resources in one request with _count

By default, a conditional delete requires your search criteria to match exactly one resource. To delete multiple matching resources in a single request, include the _count query parameter. When _count is present, HealthLake processes the request as a batch operation. It searches for matching resources, deletes them, and returns HTTP 200 with a FHIR Bundle of type batch-response that contains a per-resource status.

Example request

The following request deletes matching Coverage resources tagged inactive:

DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Coverage?_tag=inactive&_count=50

Batch response format

A request that includes _count returns HTTP 200 with a batch-response Bundle. Each entry reports the outcome for one matched resource:

As with any FHIR search, the order in which resources are matched and deleted follows the order of the underlying search results. The search doesn't guarantee this order unless you include the _sort parameter in your search criteria. If you need a deterministic order across paginated batch deletes, specify _sort. For more information, see Search parameters.

Within the response Bundle, entry order is likewise not guaranteed. Match each entry to its resource using the location field in the entry's response, rather than relying on entry position.

Partial success (version conflict)

A resource can be modified between the search and the delete. Successfully deleted resources return 204; conflicting resources return 412 in the same Bundle.

{
  "resourceType": "Bundle",
  "type": "batch-response",
  "entry": [
    {
      "response": {
        "status": "204",
        "location": "Coverage/b807f9ff-2872-45df-9325-0b2efe42e554"
      }
    },
    {
      "response": {
        "status": "412",
        "location": "Coverage/5287b322-d7e5-4688-bd55-022067db4d0f",
        "outcome": {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "exception",
              "diagnostics": "Resource was modified by another operation. Retry the request."
            }
          ]
        }
      }
    }
  ]
}

Deleting more matches with pagination

A single request deletes at most one page of matches. If more matching resources remain, the response Bundle includes a link with a next relation and a URL. Send an HTTP DELETE request to that URL to delete the next page, and repeat until the response no longer contains a next link. The next link must be followed with DELETE (the same method as the original request), not GET.

{
  "resourceType": "Bundle",
  "type": "batch-response",
  "link": [
    {
      "relation": "next",
      "url": "https://healthlake.us-east-1.amazonaws.com/...<page_token>"
    }
  ],
  "entry": [
    {
      "response": {
        "status": "204",
        "location": "Patient/4aeffdc9-6ac5-46ff-be10-bf8bd74dfecc"
      }
    }
  ]
}

SMART on FHIR authorization behavior

For more information about configuring SMART on FHIR authorization, see SMART on FHIR.

How service quotas apply

Batch conditional delete does not have its own service quota. Each request draws on the same existing HealthLake quotas as the search and delete interactions it performs, so a single request consumes multiple quota units:

Throughput is governed by your data store's write capacity. To manage throughput within your account's quota limits, either issue more requests with a smaller _count value, or use a narrower search with a larger _count value. For your account's current search and write capacity limits, see Endpoints and quotas.

Considerations