Skip to main content

Conditional PUT

info

Conditional Updates apply to PUT, PATCH and DELETE operations.

Lets create a Patient

curl --request PUT 'http://localhost/fhir/acme/Patient/100' \
--header 'Content-Type: application/json' \
--data '{
  "resourceType": "Patient",
  "id": "100",
  "name": [
    {
      "use": "official",
      "family": "Doe",
      "given": ["John"]
    }
  ],
  "gender": "male",
  "birthDate": "1990-01-01"
}'

Response:

{"resourceType":"Patient","id":"100","meta":{"versionId":"1","lastUpdated":"2025-10-09T17:41:14.645+00:00","tag":[{"system":"http://couchbase.fhir.com/fhir/custom-tags","code":"created-by","display":"user:anonymous"}]},"name":[{"use":"official","family":"Doe","given":["John"]}],"gender":"male","birthDate":"1990-01-01"}

Lets add deceasedDateTime, but this time, lets say we do not know the id but search for name.

curl --request PUT 'http://localhost/fhir/acme/Patient?name=Doe' \
--header 'Content-Type: application/json' \
--data '{
  "resourceType": "Patient",
  "name": [
    {
      "use": "official",
      "family": "Doe",
      "given": ["John"]
    }
  ],
  "gender": "male",
  "birthDate": "1990-01-01",
  "deceasedDateTime": "2022-07-22"
}'

Response:

{"resourceType":"Patient","id":"100","meta":{"versionId":"2","lastUpdated":"2025-10-09T17:51:51.025+00:00","tag":[{"system":"http://couchbase.fhir.com/fhir/custom-tags","code":"updated-by","display":"user:anonymous"}]},"name":[{"use":"official","family":"Doe","given":["John"]}],"gender":"male","birthDate":"1990-01-01","deceasedDateTime":"2022-07-22"}

Method​

  • If a single Patient matches (family="Doe"), the server will update that resource and replace all fields with those provided in your body.
  • If no Patient matches, a new resource is created with server-assigned ID.
  • If multiple matches exist, the server returns an error due to ambiguity.

Operation​

  • The server will search for a Patient with the name "Doe".
  • If one exists, it will be fully replaced by this content.
  • If none exists, a new Patient is created and assigned a new server-generated id.
  • If multiple match, the server will reject with an error due to ambiguity.
tip

For this usage, it's best to ensure your search criteria are unique enough to avoid multiple matches.

Behavior (FHIR R4)​

  • Exactly 1 match → the matched resource is fully replaced by the request body.
    • HTTP 200 OK
  • 0 matches → a new resource is created with a server-assigned id.
    • HTTP 201 Created
  • > 1 matches → ambiguous; the server must reject the operation.
    • HTTP 412 Precondition Failed

Note: On conditional PUT, any id inside the body is ignored. The target id is determined by the match (or by creation if no match).

Best practice: use a unique key​

Using name can be ambiguous. Prefer a unique identifier:

PUT /fhir/<bucket>/Patient?identifier=http://hospital.smarthealthit.org|1032702

Quick comparison​

Operation0 matches1 match>1 matches
Conditional PUT201 Created (new id)200 OK (replace)412 Precondition Failed
Conditional PATCH404 Not Found200 OK (patch)412 Precondition Failed

Notes and reminders​

  • PUT replaces the entire resource. Fields not present in the body are removed. Use PATCH for partial changes.
  • On success, the server updates meta.lastUpdated, increments meta.versionId, and sets audit tags (created-by / updated-by).
  • If your bucket enforces US Core, the server may set meta.profile accordingly and apply profile validation (Strict / Lenient / Disabled).