Update Resource

curl --request PUT \
  --url http://localhost:8080/fhir/{resourceType}/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/fhir+json' \
  --data '
{
  "resourceType": "<string>"
}
'

import requests

url = "http://localhost:8080/fhir/{resourceType}/{id}"

payload = { "resourceType": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/fhir+json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/fhir+json'},
  body: JSON.stringify({resourceType: '<string>'})
};

fetch('http://localhost:8080/fhir/{resourceType}/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "resourceType": "Patient",
  "id": "123",
  "meta": {
    "versionId": "6",
    "lastUpdated": "2026-01-12T14:30:00.000Z"
  },
  "name": [
    {
      "family": "Doe",
      "given": ["Jane", "Marie"]
    }
  ],
  "gender": "female",
  "birthDate": "1990-01-01",
  "identifier": [
    {
      "system": "http://hospital.example/mrn",
      "value": "12345"
    }
  ],
  "telecom": [
    {
      "system": "email",
      "value": "jane.doe@example.com",
      "use": "home"
    }
  ],
  "active": true
}

HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"6"
Last-Modified: Mon, 12 Jan 2026 14:30:00 GMT
Content-Location: /fhir/Patient/123/_history/6

PUT

{resourceType}

{id}

Update Resource

curl --request PUT \
  --url http://localhost:8080/fhir/{resourceType}/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/fhir+json' \
  --data '
{
  "resourceType": "<string>"
}
'

import requests

url = "http://localhost:8080/fhir/{resourceType}/{id}"

payload = { "resourceType": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/fhir+json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/fhir+json'},
  body: JSON.stringify({resourceType: '<string>'})
};

fetch('http://localhost:8080/fhir/{resourceType}/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "resourceType": "Patient",
  "id": "123",
  "meta": {
    "versionId": "6",
    "lastUpdated": "2026-01-12T14:30:00.000Z"
  },
  "name": [
    {
      "family": "Doe",
      "given": ["Jane", "Marie"]
    }
  ],
  "gender": "female",
  "birthDate": "1990-01-01",
  "identifier": [
    {
      "system": "http://hospital.example/mrn",
      "value": "12345"
    }
  ],
  "telecom": [
    {
      "system": "email",
      "value": "jane.doe@example.com",
      "use": "home"
    }
  ],
  "active": true
}

HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"6"
Last-Modified: Mon, 12 Jan 2026 14:30:00 GMT
Content-Location: /fhir/Patient/123/_history/6

Replaces an existing resource with a new version. The entire resource must be provided (not partial updates - use PATCH for that).

Endpoint

PUT /fhir/{resourceType}/{id}

string

required

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

string

required

The logical ID of the resource to update

Headers

string

required

Must be application/fhir+json or application/fhir+xml

string

Response format: application/fhir+json (default) or application/fhir+xml

string

Conditional update. Only update if current version matches this ETag. Example: W/"5" - Prevents lost updates via optimistic locking

string

Response style: - return=representation (default) - Return full updated resource - return=minimal - Return headers only - return=OperationOutcome

Return OperationOutcome

Query Parameters

string

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

Request Body

The complete resource including the ID. Missing fields are removed (not preserved).

{
  "resourceType": "Patient",
  "id": "123",
  "name": [
    {
      "family": "Doe",
      "given": ["Jane", "Marie"]
    }
  ],
  "gender": "female",
  "birthDate": "1990-01-01",
  "identifier": [
    {
      "system": "http://hospital.example/mrn",
      "value": "12345"
    }
  ],
  "telecom": [
    {
      "system": "email",
      "value": "jane.doe@example.com",
      "use": "home"
    }
  ],
  "active": true
}

{
  "resourceType": "Observation",
  "id": "456",
  "status": "amended",
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "8867-4",
        "display": "Heart rate"
      }
    ]
  },
  "subject": {
    "reference": "Patient/123"
  },
  "valueQuantity": {
    "value": 75,
    "unit": "beats/minute",
    "system": "http://unitsofmeasure.org",
    "code": "/min"
  }
}

Total Replacement: PUT replaces the entire resource. Any fields not included in the request body are removed. Use PATCH for partial updates.

Response

200 OK

Resource updated successfully.

string

required

New version number (incremented from previous)

string

required

ISO 8601 timestamp of this update

{
  "resourceType": "Patient",
  "id": "123",
  "meta": {
    "versionId": "6",
    "lastUpdated": "2026-01-12T14:30:00.000Z"
  },
  "name": [
    {
      "family": "Doe",
      "given": ["Jane", "Marie"]
    }
  ],
  "gender": "female",
  "birthDate": "1990-01-01",
  "identifier": [
    {
      "system": "http://hospital.example/mrn",
      "value": "12345"
    }
  ],
  "telecom": [
    {
      "system": "email",
      "value": "jane.doe@example.com",
      "use": "home"
    }
  ],
  "active": true
}

HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"6"
Last-Modified: Mon, 12 Jan 2026 14:30:00 GMT
Content-Location: /fhir/Patient/123/_history/6

201 Created

Resource created (update-as-create). Occurs when the resource doesn’t exist and server allows creation via PUT.

{
  "resourceType": "Patient",
  "id": "new-patient-123",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2026-01-12T14:30:00.000Z"
  },
  "name": [
    {
      "family": "Doe",
      "given": ["John"]
    }
  ]
}

HTTP/1.1 201 Created
Location: /fhir/Patient/new-patient-123
ETag: W/"1"
Content-Type: application/fhir+json

Update-as-Create: Whether PUT can create resources (when they don’t exist) depends on server configuration. Check the CapabilityStatement for updateCreate support.

400 Bad Request

Validation failed or malformed request.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "expression": ["Patient.id"],
      "diagnostics": "Resource ID in body (999) does not match URL (123)"
    }
  ]
}

404 Not Found

Resource doesn’t exist and server doesn’t support update-as-create.

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

409 Conflict

Version conflict or referential integrity violation.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "conflict",
      "diagnostics": "Version conflict: current version is 7, provided If-Match is W/\"5\""
    }
  ]
}

412 Precondition Failed

Conditional update matched multiple resources (ambiguous) or If-Match failed.

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

Examples

curl -X PUT "https://your-server.com/fhir/Patient/123" \
  -H "Content-Type: application/fhir+json" \
  -H "Accept: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "id": "123",
    "name": [{"family": "Doe", "given": ["Jane"]}],
    "gender": "female",
    "birthDate": "1990-01-01"
  }'

# First, read the resource to get current ETag
curl -i "https://your-server.com/fhir/Patient/123"
# Note the ETag: W/"5"

# Then update with If-Match to prevent lost updates
curl -X PUT "https://your-server.com/fhir/Patient/123" \
  -H "Content-Type: application/fhir+json" \
  -H "Accept: application/fhir+json" \
  -H 'If-Match: W/"5"' \
  -d '{
    "resourceType": "Patient",
    "id": "123",
    "name": [{"family": "Doe", "given": ["Jane", "Marie"]}],
    "gender": "female",
    "birthDate": "1990-01-01"
  }'

curl -X PUT "https://your-server.com/fhir/Patient?identifier=http://hospital.example/mrn|12345" \
  -H "Content-Type: application/fhir+json" \
  -H "Accept: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "identifier": [{"system": "http://hospital.example/mrn", "value": "12345"}],
    "name": [{"family": "Doe", "given": ["Jane"]}]
  }'

curl -X PUT "https://your-server.com/fhir/Patient/my-custom-id" \
  -H "Content-Type: application/fhir+json" \
  -H "Accept: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "id": "my-custom-id",
    "name": [{"family": "Doe", "given": ["John"]}]
  }'

import requests

url = "https://your-server.com/fhir/Patient/123"
headers = {
    "Content-Type": "application/fhir+json",
    "Accept": "application/fhir+json"
}

# Read current version
response = requests.get(url, headers={"Accept": "application/fhir+json"})
patient = response.json()
etag = response.headers['ETag']

# Modify patient
patient['name'][0]['given'] = ['Jane', 'Marie']
patient['telecom'] = [
    {
        "system": "email",
        "value": "jane.doe@example.com"
    }
]

# Update with optimistic locking
headers['If-Match'] = etag
response = requests.put(url, json=patient, headers=headers)

if response.status_code == 200:
    updated = response.json()
    print(f"Updated to version {updated['meta']['versionId']}")
elif response.status_code == 412:
    print("Version conflict - resource was modified by someone else")

const url = "https://your-server.com/fhir/Patient/123";

// Read current version
let response = await fetch(url, {
  headers: { Accept: "application/fhir+json" },
});
const patient = await response.json();
const etag = response.headers.get("ETag");

// Modify patient
patient.name[0].given = ["Jane", "Marie"];
patient.active = true;

// Update with optimistic locking
response = await fetch(url, {
  method: "PUT",
  headers: {
    "Content-Type": "application/fhir+json",
    Accept: "application/fhir+json",
    "If-Match": etag,
  },
  body: JSON.stringify(patient),
});

if (response.status === 200) {
  const updated = await response.json();
  console.log(`Updated to version ${updated.meta.versionId}`);
} else if (response.status === 412) {
  console.log("Version conflict - retry needed");
}

Best Practices

Always Use If-Match: Include the If-Match header with the current ETag to prevent lost updates in concurrent scenarios. Without it, last write wins.

Complete Resource Required: You must send the entire resource. Missing fields are removed. Common mistake:

Bad - Missing fields will be deleted

{
  "resourceType": "Patient",
  "id": "123",
  "name": [{ "family": "NewName" }]
  // Oops! gender, birthDate, identifier all deleted
}

For partial updates, use PATCH instead.

ID Consistency: The id in the request body must match the id in the URL. The resourceType must also match.

Patch Resource

Partial updates without replacing entire resource

Read Resource

Get current version before updating

Resource History

View update history

Learn FHIR CRUD

Understand FHIR update semantics

Authorizations

Authorization

string

header

required

Bearer token authentication

Headers

If-Match

string

For version-aware updates

Path Parameters

resourceType

string

required

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

string

required

The logical ID of the resource

Body

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

resourceType

string

required

The type of resource

string

Logical id of this artifact

Response

Resource updated

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

resourceType

string

required

The type of resource

string

Logical id of this artifact

Overview

Metadata

CRUD Operations

Search

History & Versioning

Batch & Transaction

Operations

Update Resource

Endpoint

Headers

Query Parameters

Request Body

Response

200 OK

201 Created

400 Bad Request

404 Not Found

409 Conflict

412 Precondition Failed

Examples

Best Practices

See Also

Patch Resource

Read Resource

Resource History

Learn FHIR CRUD

Authorizations

Headers

Path Parameters

Body

Response

​Endpoint

​Headers

​Query Parameters

​Request Body

​Response

​200 OK

​201 Created

​400 Bad Request

​404 Not Found

​409 Conflict

​412 Precondition Failed

​Examples

​Best Practices

​See Also

Patch Resource

Read Resource

Resource History

Learn FHIR CRUD

Authorizations

Headers

Path Parameters

Body

Response

Endpoint

Headers

Query Parameters

Request Body

Response

200 OK

201 Created

400 Bad Request

404 Not Found

409 Conflict

412 Precondition Failed

Examples

Best Practices

See Also