Partial updates: PATCH vs PUT

AgencyMax APIs use PATCH and PUT in different ways, so it matters which one an operation uses.

PATCH: only what you send changes

A PATCH updates only the properties in the request body. Each property can be in one of three states:

In the request body	Result
Property omitted	The value is unchanged.
Property set to a value	The value is replaced.
Property set to null	The value is cleared, where the field allows it.

For example, suppose certification 812 has a note and is unverified:

PATCH /agency-management/acme/certifications/812
Content-Type: application/json

{
  "isVerified": true,
  "initiator": "jsmith"
}

This marks the certification as verified and leaves the note alone. To clear the note, send it explicitly as null:

{
  "note": null,
  "initiator": "jsmith"
}

warning

Serializers that omit nulls

Many JSON serializers leave out null properties by default, for example System.Text.Json with DefaultIgnoreCondition = WhenWritingNull, or Newtonsoft.Json with NullValueHandling.Ignore. Because of this, an intended "clear" can become "no change". Make sure your PATCH bodies can include explicit nulls.

Setting a required field to null is a validation error.

PUT: full replacement

A PUT replaces the whole resource. Every property is applied, and an omitted property counts as null, so it gets cleared.

Operations that use PUT:

• Agent Onboarding PUT /applications/{id}. A section left out of the request, such as w9 or employment, is cleared. See Applications.
• Webhooks PUT /subscriptions/{id}. This one is an exception: omitted properties are left unchanged. See Subscriptions.

To make a partial change with a true PUT, read the resource, change it and send the whole thing back.