Skip to main content

Versioning Notices

This guide is the practical, integration-facing companion to the conceptual explanation in Consent Notices → noticeGroupKey. Read that first if you haven't.

The one rule​

Always resolve the current notice by groupKey + lang. Never hardcode a notice id.

// Do this — resolves to whatever's currently ACTIVE, forever
const res = await fetch(`${CMP_BASE}/notice?groupKey=privacy-policy&lang=en`, {
headers: { "X-Org-Api-Key": API_KEY },
});

// Don't do this — id=12 will eventually be archived and this call will 404
const res = await fetch(`${CMP_BASE}/notices/12`); // (this endpoint doesn't even exist publicly, by design)

What happens when a notice is republished​

When an org publishes a new version of privacy-policy/en:

  1. The previously-ACTIVE version transitions to ARCHIVED.
  2. A new version becomes ACTIVE with version incremented by one.
  3. Your next GET /notice?groupKey=privacy-policy&lang=en call returns the new version automatically — same groupKey, new id, new version, potentially new title/content/purposes.

Existing consent records are not touched. A principal who consented under version 2 still has a consent record pointing at version 2's id — that's what makes it valid historical evidence.

Detecting "this principal consented under an old version"​

If you're using the hosted widget, this is handled for you automatically — skip to the next section unless you're building a fully custom integration against the raw API.

Each purpose in the purposes array returned by GET /notice carries a requiresReconsent boolean, computed once at publish time by comparing that purpose against its same-purposeCode counterpart on the previous version:

{
"purposeCode": "advertising_cookies",
"name": "Advertising",
"requiresReconsent": true
}

requiresReconsent is true if the purpose is brand new, or if its legalBasis, retentionPeriodDays, mandatory flag, restrictedForMinors flag, or data categories changed since the version a principal may have already consented under. It's false if the purpose carried over unchanged — including the common case of a notice being republished for a reason that has nothing to do with any purpose (a copy-editing fix to the notice content, for example), where nothing should be re-prompted at all even though the notice got a new id.

The correct comparison is per-purpose, not "does the notice id match" — a blunt notice-id check would force a full reprompt on any republish, including ones that changed nothing a principal actually needs to reconsider. Build it like this:

  1. Fetch the current notice via GET /notice?groupKey=....
  2. For each purpose in the response: if requiresReconsent is true, treat it as undecided regardless of whatever you have stored for that purposeCode from a prior grant — default it to not-granted until the principal explicitly chooses again. If requiresReconsent is false, carry forward whatever you had stored for that purposeCode.
  3. If any purpose came out undecided in step 2, re-prompt — ideally naming which purpose(s) changed, so the principal understands why they're being asked again, rather than re-showing the exact same first-time prompt text.

This mirrors how the hosted widget itself behaves, and matches the DPDPA Sec 6 principle that consent must be specific to what's actually being processed — a principal's prior "yes" can't be assumed to cover a purpose that didn't exist, or covered different terms, when they agreed to it.

Multi-language notices publish independently​

Each (noticeGroupKey, language) pair versions on its own. Publishing a new English version of privacy-policy does not archive or otherwise affect the Hindi (hi) version of the same groupKey — they're tracked completely separately. If your product supports multiple languages, make sure whatever republish/re-consent detection you build (above) is scoped per-language, not just per-groupKey.