Skip to main content
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 '
[
  {
    "op": "add",
    "path": "<string>",
    "value": "<unknown>",
    "from": "<string>"
  }
]
'
{
  "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": "[email protected]"
    }
  ]
}
Applies partial modifications to a resource without replacing it entirely. Unlike PUT, only the specified fields are changed.

​
Endpoint

PATCH /fhir/{resourceType}/{id}
​
resourceType
string
required
The FHIR resource type (e.g., Patient, Observation, Encounter)
​
id
string
required
The logical ID of the resource to patch

​
Headers

​
Content-Type
string
required
Patch format:
  • application/json-patch+json - JSON Patch (RFC 6902)
  • application/fhir+json - FHIRPath Patch (Parameters resource)
​
Accept
string
Response format: application/fhir+json (default) or application/fhir+xml
​
If-Match
string
Conditional patch. Only patch if current version matches this ETag.Example: W/"5"
​
Prefer
string
Response style:
  • return=representation (default) - Return full patched resource
  • return=minimal - Return headers only
  • return=OperationOutcome - Return OperationOutcome

​
Query Parameters

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

​
Request Body

Array of patch operations following RFC 6902: 
[
  {
    "op": "replace",
    "path": "/name/0/given/0",
    "value": "Jane"
  }
]
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.
​
meta.versionId
string
required
New version number (incremented)
​
meta.lastUpdated
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": "[email protected]"
    }
  ]
}
Narrative Removed: Some servers (including TLQ) 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"
    }
  ]'

​
JSON Patch Path Syntax

Paths use JSON Pointer notation (RFC 6901):
PathMeaning
/nameRoot-level name field
/name/0First element of name array
/name/0/givengiven field of first name
/name/0/given/0First 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": "[email protected]"
    }
  }
]

​
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" }
]

​
See Also

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)

​
id
string
required

The logical ID of the resource

Body

​
op
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

​
id
string

Logical id of this artifact

​
meta
object

Metadata about a resource