About the CMS Compliance API

The CMS Compliance API lets apps request a compliance review of CMS content actions at the site or account level. Supported actions include publishing a new draft, publishing a changed or unchanged item, and unpublishing an item with or without pending edits.

With the CMS Compliance API, you can:

Submit a single CMS data item for compliance review.
Submit a batch of data items from the same collection for review in one call.
Receive review requests as a webhook: one event for each single submission, and one event carrying the whole batch for each bulk call.
Compare an item's published and proposed versions, for the actions that return both.

For each successful request, the service fetches the required CMS data item versions, returns a ComplianceReviewRequest for every submitted item, and emits the same objects in a domain event. Authorized consumers can subscribe to the event as a webhook and process the requests in their own review, approval, or rejection workflow.

The service is independent of the calling UI and doesn't track or apply the review outcome.

How it works

Call Request Review with the action, data item ID, and collection ID. For UNPUBLISH_CHANGED, you can also specify which version should remain as the saved draft.

The action determines which CMS data item versions the service reads and returns:

PUBLISH_DRAFT: the proposed draft only, because nothing is live yet.
PUBLISH_CHANGED: the current published version and proposed draft.
PUBLISH_PUBLISHED: the same published item as both the current and proposed version.
UNPUBLISH_PUBLISHED: the current published version only.
UNPUBLISH_CHANGED: the current published version and proposed draft, plus the optional version the user wants to preserve as a draft.

The currentDataItem is the version that's currently published. The proposedDataItem is the version submitted for review. Comparing them shows whether the request introduces a content change.

Reviewing items in a batch

To submit several data items at once, call Bulk Request Review with a single collectionId and a list of items. Each item carries the same action, dataItemId, and versionOnUnpublish fields as a single request, and the actions within one call can differ from each other. The service applies the matrix above to each item on its own, so a batch that combines PUBLISH_DRAFT and PUBLISH_CHANGED returns one review request holding only proposedDataItem and another holding both versions.

A batch is all-or-nothing. The service fetches the data item versions the whole batch needs together, in a single CMS query per collection version, so the outcome is shared by every item in the call: either all the review requests are built and emitted in one Bulk Review Requested event, or the call fails and nothing is emitted. There's no partial success, and no per-item error to inspect.

Before you begin

It's important to note the following points before starting to code:

To consume review requests, subscribe to the Review Requested webhook, the Bulk Review Requested webhook, or both. Single calls and batches don't trigger the same webhook, so subscribing to one means the other goes unnoticed. The API doesn't store review requests, so there's no endpoint to query them later.
versionOnUnpublish is used only for UNPUBLISH_CHANGED. It can be omitted, and is ignored for every other action.
Every data item in a batch must already exist in the collection version its action requires. If any item is missing, the whole call fails with DATA_ITEMS_NOT_FOUND and nothing is emitted.
Content is read from the CMS when the call is made, and CMS reads are eventually consistent. An item updated immediately beforehand may be fetched without its latest change. See the CMS Data Items API for more information.

Use cases

Terminology