---
title: "Update arbitrary metadata on an engagement"
method: PATCH
path: "/api/v1/engagements/{engagement_id}/context/metadata"
tags: ["Engagements"]
---

# Update arbitrary metadata on an engagement

`PATCH /api/v1/engagements/{engagement_id}/context/metadata`

## Request

- Base URL: `https://api.cloverhealth.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.cloverhealth.com/api/v1/engagements/{engagement_id}/context/metadata`
- Auth: API key in header `X-MC2-Signature`

Requires scope: engagement:context:update

Deep-merges `metadata` into the Engagement's existing metadata blob: where
a key is a dict on both sides it's merged recursively rather than
replaced outright, any other value (scalar or list) is replaced, and
keys not included here are left untouched at every level, so a
concurrent writer's keys (e.g. disposition_service) survive.

`master_record_id`, when provided either as its own field or as a key
inside `metadata`, also sets the Engagement's `master_record_id` column
(read by `get_basic_context_payload` for the member lookup) -- mirroring
disposition_service.write_disposition's precedent of writing the id to
the column AND leaving it in the blob. Overwriting an already-set id is
logged to `EngagementActivityLog`; the first null -> id assignment is
not, since that's the normal outcome of IVR/ANI identification rather
than a notable identity correction.

The `disposition` key is reserved for CMS call-logging compliance data
(see docs/CMS_CALL_LOGGING_COMPLIANCE.md) and is rejected here with 400 —
use the dedicated disposition service to write it.

## Path parameters

- `engagement_id` string, uuid, required

## Request body

- EngagementMetadataUpdateRequest: Arbitrary key/value updates to merge into an Engagement's metadata blob. `master_record_id` also sets the Engagement's `master_record_id` column (not just a metadata key) whether it's given here as its own field or as a `master_record_id` key inside `metadata` -- this field takes precedence if both are given (see context_service.merge_metadata).
  - `metadata` object, required
  - `master_record_id` string, nullable

## Response `200`

OK

- EngagementMetadataUpdateResponse
  - `engagement_id` string, uuid, required

## Other responses

- `400`: Bad Request
- `404`: Not Found

## Changes

- **2026-09-22** `b9fde795fc76`: 1 info
  - added the new optional request property `master_record_id`
- **2026-09-14** `6d503b8b9ad9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloverhealth/apis/clover-api/changes/api/v1/engagements/:engagement_id/context/metadata/patch.md)

---

[API](https://skmtc.dev/cloverhealth/apis/clover-api.md) - [All operations](https://skmtc.dev/cloverhealth/apis/clover-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloverhealth/apis/clover-api/revisions/824d541751f2?raw)