Create, Update, and Restore Resources with PUT

Check availability

Check the target resource in the deployed server's CapabilityStatement. A resource with updateCreate=true supports creation and restoration with PUT. This capability also applies to supported batch PUT entries.

Choose a logical ID

Logical IDs are case-sensitive strings of 1 to 64 ASCII letters, digits, hyphens, or periods, matching [A-Za-z0-9.-]{1,64}. For example, Client.123-A and client.123-a are different identities. UUIDs are supported. An identity is scoped to its resource type: Patient/Client.123-A and Device/Client.123-A do not collide.

Preserve the exact ID when reading, searching with _id, reading historical versions, constructing local references, updating, or deleting. Percent-encode path components and query values when constructing URLs.

Clients are responsible for coordinating assigned IDs. PUT to an occupied ID updates its existing resource; it does not detect whether that identity belongs to the same record in your source system. Use a collision-resistant ID allocation strategy and the supported version preconditions when replacing an existing representation. POST assigns an ID on the server and ignores a submitted client ID.

Create, replace, and restore

PUT [base]/Patient/Client.123-A
Content-Type: application/fhir+json
Prefer: return=representation

{"resourceType":"Patient","id":"Client.123-A","active":true}

The body must contain the requested resource type and an ID identical to the URL ID. Missing or mismatched IDs, wrong resource types, malformed content, and basic FHIR validation failures return 400 with a safe FHIR OperationOutcome. Applicable business-rule rejection returns 422.

The server assigns meta.versionId and meta.lastUpdated and ignores submitted values for these fields. Successful PUT responses include the resulting ETag, Last-Modified, and version-specific Location, such as [base]/Patient/Client.123-A/_history/1.

Prefer: return=representation returns the persisted resource; return=minimal returns no body; return=OperationOutcome returns an informational outcome. Status and version headers still identify the committed result. Without a return preference, the server returns the representation.

Creation and restoration apply the resource's create validation and lifecycle rules. For example, a restored R6 Subscription must satisfy subscription creation rules and complete its handshake before becoming active.

Permissions and version preconditions

Creation and restoration require both create and update permission. For example, grant and request ddfssystem/Patient.cu; the issued token uses system/Patient.cu. Updating a live resource requires update permission, such as system/Patient.u. Applicable resource-access constraints apply to the existing resource and the submitted replacement. An authenticated caller without the required permissions receives a safe 403 outcome without a write.

Use If-Match: W/"4" to replace version 4. A nonmatching condition returns 412 Precondition Failed without writes. Any supplied valid If-Match condition, including *, requires an existing target and cannot create an unused ID. For restoration, compare against the current deletion version, not the last live version. Malformed If-Match headers return 400.

Competing writes can return 409 Conflict or, when a version precondition loses a race, 412. Read the current state and decide whether a retry is appropriate. Rejected writes do not change the resource, its history, or related FHIR records.

Use PUT in a batch

The FHIR batch interaction accepts PUT entries with the same ID, authorization, validation, and create/update/restore behavior. Each response entry reports its own status, version headers, and representation. Entries remain independent: a failed entry does not roll back successful unrelated entries. Batch entries must be independent. Conditional request fields, including entry.request.ifMatch, are unsupported; use a direct PUT when you need If-Match protection. See Send Independent Requests in a Batch.

Versioned standards

See the FHIR R4 update requirements and FHIR R6 Ballot 4 update requirements.