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:
- The previously-
ACTIVEversion transitions toARCHIVED. - A new version becomes
ACTIVEwithversionincremented by one. - Your next
GET /notice?groupKey=privacy-policy&lang=encall returns the new version automatically — same groupKey, newid, newversion, potentially newtitle/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:
- Fetch the current notice via
GET /notice?groupKey=.... - For each purpose in the response: if
requiresReconsentistrue, treat it as undecided regardless of whatever you have stored for thatpurposeCodefrom a prior grant — default it to not-granted until the principal explicitly chooses again. IfrequiresReconsentisfalse, carry forward whatever you had stored for thatpurposeCode. - 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.