Patch Resource

curl --request PATCH \
  --url http://localhost:8080/fhir/{resourceType}/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
[
  {
    "path": "<string>",
    "value": "<unknown>",
    "from": "<string>"
  }
]
'

import requests

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

payload = [
    {
        "path": "<string>",
        "value": "<unknown>",
        "from": "<string>"
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify([{path: '<string>', value: '<unknown>', from: '<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-12T15:00:00.000Z"
  },
  "name": [
    {
      "family": "Doe",
      "given": ["Jane"]
    }
  ],
  "gender": "female",
  "birthDate": "1990-01-01",
  "active": true,
  "telecom": [
    {
      "system": "email",
      "value": "jane@example.com"
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"6"
Last-Modified: Mon, 12 Jan 2026 15:00:00 GMT

PATCH

{resourceType}

{id}

Patch Resource

curl --request PATCH \
  --url http://localhost:8080/fhir/{resourceType}/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
[
  {
    "path": "<string>",
    "value": "<unknown>",
    "from": "<string>"
  }
]
'

import requests

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

payload = [
    {
        "path": "<string>",
        "value": "<unknown>",
        "from": "<string>"
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify([{path: '<string>', value: '<unknown>', from: '<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-12T15:00:00.000Z"
  },
  "name": [
    {
      "family": "Doe",
      "given": ["Jane"]
    }
  ],
  "gender": "female",
  "birthDate": "1990-01-01",
  "active": true,
  "telecom": [
    {
      "system": "email",
      "value": "jane@example.com"
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"6"
Last-Modified: Mon, 12 Jan 2026 15:00:00 GMT

Applies partial modifications to a resource without replacing it entirely. Unlike PUT, only the specified fields are changed.

Endpoint

PATCH /fhir/{resourceType}/{id}

string

required

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

string

required

The logical ID of the resource to patch

Headers

string

required

Patch format:

application/json-patch+json - JSON Patch (RFC 6902)
application/fhir+json - FHIRPath Patch (Parameters resource)

string

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

string

Conditional patch. Only patch if current version matches this ETag.Example: W/"5"

string

Response style:

return=representation (default) - Return full patched resource
return=minimal - Return headers only
return=OperationOutcome - Return OperationOutcome

Query Parameters

string

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

Request Body

JSON Patch Format (Recommended)

Array of patch operations following RFC 6902:

[
  {
    "op": "replace",
    "path": "/name/0/given/0",
    "value": "Jane"
  }
]

[
  {
    "op": "add",
    "path": "/telecom/0",
    "value": {
      "system": "email",
      "value": "jane@example.com"
    }
  }
]

[
  {
    "op": "remove",
    "path": "/address/0"
  }
]

[
  {
    "op": "replace",
    "path": "/name/0/given/0",
    "value": "Jane"
  },
  {
    "op": "add",
    "path": "/active",
    "value": true
  },
  {
    "op": "remove",
    "path": "/photo"
  }
]

Supported Operations:

add - Add a value (creates if missing, appends to arrays)
remove - Remove a value
replace - Replace a value (must exist)
move - Move a value from one path to another
copy - Copy a value from one path to another
test - Assert a value matches (fails patch if doesn’t match)

FHIRPath Patch Format

FHIR Parameters resource with FHIRPath expressions:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueCode": "replace"
        },
        {
          "name": "path",
          "valueString": "Patient.name[0].given[0]"
        },
        {
          "name": "value",
          "valueString": "Jane"
        }
      ]
    }
  ]
}

Format Support: Most servers support JSON Patch. FHIRPath Patch support varies. Check the server’s CapabilityStatement.

Response

200 OK

Resource patched successfully.

string

required

New version number (incremented)

string

required

ISO 8601 timestamp of this patch

{
  "resourceType": "Patient",
  "id": "123",
  "meta": {
    "versionId": "6",
    "lastUpdated": "2026-01-12T15:00:00.000Z"
  },
  "name": [
    {
      "family": "Doe",
      "given": ["Jane"]
    }
  ],
  "gender": "female",
  "birthDate": "1990-01-01",
  "active": true,
  "telecom": [
    {
      "system": "email",
      "value": "jane@example.com"
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"6"
Last-Modified: Mon, 12 Jan 2026 15:00:00 GMT

Narrative Removed: Some servers (including Ferrum) remove the text (narrative) field after patching to prevent serving stale human-readable content.

400 Bad Request

Invalid patch operation or resulting resource invalid.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Invalid patch operation: path '/invalid/path' not found in resource"
    }
  ]
}

404 Not Found

Resource doesn’t exist.

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

412 Precondition Failed

Conditional patch failed (multiple matches or If-Match mismatch).

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

422 Unprocessable Entity

Patch applied but resulting resource violates validation rules.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "business-rule",
      "expression": ["Patient.name"],
      "diagnostics": "Patient must have at least one name"
    }
  ]
}

Examples

curl -X PATCH "https://your-server.com/fhir/Patient/123" \
  -H "Content-Type: application/json-patch+json" \
  -H "Accept: application/fhir+json" \
  -d '[
    {
      "op": "replace",
      "path": "/name/0/given/0",
      "value": "Jane"
    }
  ]'

curl -X PATCH "https://your-server.com/fhir/Patient/123" \
  -H "Content-Type: application/json-patch+json" \
  -H "Accept: application/fhir+json" \
  -d '[
    {
      "op": "add",
      "path": "/telecom/0",
      "value": {
        "system": "email",
        "value": "jane@example.com"
      }
    },
    {
      "op": "add",
      "path": "/active",
      "value": true
    }
  ]'

curl -X PATCH "https://your-server.com/fhir/Patient/123" \
  -H "Content-Type: application/json-patch+json" \
  -H "Accept: application/fhir+json" \
  -d '[
    {
      "op": "remove",
      "path": "/photo"
    }
  ]'

curl -X PATCH "https://your-server.com/fhir/Patient?identifier=http://hospital.example/mrn|12345" \
  -H "Content-Type: application/json-patch+json" \
  -H "Accept: application/fhir+json" \
  -d '[
    {
      "op": "add",
      "path": "/active",
      "value": false
    }
  ]'

import requests

url = "https://your-server.com/fhir/Patient/123"
headers = {
    "Content-Type": "application/json-patch+json",
    "Accept": "application/fhir+json"
}
patch = [
    {
        "op": "replace",
        "path": "/name/0/given/0",
        "value": "Jane"
    },
    {
        "op": "add",
        "path": "/active",
        "value": True
    }
]

response = requests.patch(url, json=patch, headers=headers)
if response.status_code == 200:
    patient = response.json()
    print(f"Patched to version {patient['meta']['versionId']}")

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

const patch = [
  {
    op: 'replace',
    path: '/name/0/given/0',
    value: 'Jane'
  },
  {
    op: 'add',
    path: '/telecom/0',
    value: {
      system: 'email',
      value: 'jane@example.com'
    }
  }
];

const response = await fetch(url, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json-patch+json',
    'Accept': 'application/fhir+json'
  },
  body: JSON.stringify(patch)
});

if (response.status === 200) {
  const patient = await response.json();
  console.log(`Patched to version ${patient.meta.versionId}`);
}

JSON Patch Path Syntax

Paths use JSON Pointer notation (RFC 6901):

Path	Meaning
`/name`	Root-level `name` field
`/name/0`	First element of `name` array
`/name/0/given`	`given` field of first name
`/name/0/given/0`	First given name
`/telecom/-`	Append to `telecom` array (add only)

Array Indexing: Arrays are 0-indexed. Use - as the index to append to the end of an array (for add operation only).

Best Practices

Prefer PATCH over PUT: Use PATCH when you only need to change specific fields. It’s more efficient and less error-prone than reading the full resource, modifying it, and PUTting it back.

Atomic Operations: All operations in a patch are atomic. If any operation fails, the entire patch is rejected and no changes are made.

Test Operation: Use the test operation to verify a field has an expected value before applying changes. This provides additional safety:

[
  { "op": "test", "path": "/active", "value": false },
  { "op": "replace", "path": "/active", "value": true }
]

Fails if active is not currently false.

Common Use Cases

Update Single Field

[{ "op": "replace", "path": "/active", "value": false }]

Add Contact Information

[
  {
    "op": "add",
    "path": "/telecom/-",
    "value": {
      "system": "email",
      "value": "patient@example.com"
    }
  }
]

Remove Sensitive Data

[
  { "op": "remove", "path": "/photo" },
  { "op": "remove", "path": "/contact/0/telecom" }
]

Conditional Update with Safety

[
  { "op": "test", "path": "/status", "value": "draft" },
  { "op": "replace", "path": "/status", "value": "final" }
]

Update Resource

Full resource replacement with PUT

Read Resource

Get current version before patching

JSON Patch RFC

Official JSON Patch specification

Learn FHIR CRUD

Understand FHIR patch 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

Body

enum<string>

required

The operation to perform

Available options:

add,

remove,

replace,

move,

copy,

test

path

string

required

A JSON Pointer path

value

any

The value to use

from

string

A JSON Pointer path (for move/copy operations)

Response

Resource patched

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

Patch Resource

Endpoint

Headers

Query Parameters

Request Body

JSON Patch Format (Recommended)

FHIRPath Patch Format

Response

200 OK

400 Bad Request

404 Not Found

412 Precondition Failed

422 Unprocessable Entity

Examples

JSON Patch Path Syntax

Best Practices

Common Use Cases

Update Single Field

Add Contact Information

Remove Sensitive Data

Conditional Update with Safety

See Also

Update Resource

Read Resource

JSON Patch RFC

Learn FHIR CRUD

Authorizations

Path Parameters

Body

Response

​Endpoint

​Headers

​Query Parameters

​Request Body

​JSON Patch Format (Recommended)

​FHIRPath Patch Format

​Response

​200 OK

​400 Bad Request

​404 Not Found

​412 Precondition Failed

​422 Unprocessable Entity

​Examples

​JSON Patch Path Syntax

​Best Practices

​Common Use Cases

​Update Single Field

​Add Contact Information

​Remove Sensitive Data

​Conditional Update with Safety

​See Also

Update Resource

Read Resource

JSON Patch RFC

Learn FHIR CRUD

Authorizations

Path Parameters

Body

Response

Endpoint

Headers

Query Parameters

Request Body

JSON Patch Format (Recommended)

FHIRPath Patch Format

Response

200 OK

400 Bad Request

404 Not Found

412 Precondition Failed

422 Unprocessable Entity

Examples

JSON Patch Path Syntax

Best Practices

Common Use Cases

Update Single Field

Add Contact Information

Remove Sensitive Data

Conditional Update with Safety

See Also