Consent Notices
A consent notice is the actual document you show a visitor — a privacy policy, a cookie notice, a marketing-consent notice, etc. — along with the list of purposes it covers.
Fields
| Field | Type | Notes |
|---|---|---|
id | number | Specific to one version — see noticeGroupKey below for why you shouldn't hardcode this |
noticeGroupKey | string | The stable identifier for "this logical notice" — see below |
language | string | ISO-ish language code (en, hi, ta, ...) |
version | number | Increments every time this groupKey+language is republished |
title | string | Banner headline |
content | string | Markdown-authored body text |
status | enum | DRAFT (being authored, not yet visible to the public API), ACTIVE (currently live), ARCHIVED (superseded by a newer version) |
privacyPolicyUrl | string | null | A reference link to the org's own privacy policy page, if they've set one. The CMP never stores or hosts that document itself — only this link — so render it as a "Read our full Privacy Policy" link alongside the notice, not as embedded content. null if the org hasn't configured one. |
privacyPolicyVersion | string | null | A version label the org assigns their own privacyPolicyUrl document (their own scheme — "2.0", a date, anything). null if they haven't set one. Independent of version above (that only tracks this notice's own structured content — an org can update their policy's wording with no corresponding notice/purpose change at all). For an already-registered principal, prefer Check consent status's server-computed requiresPrivacyPolicyReconsent over comparing this value yourself — it's authoritative (derived from the principal's actual consent record) where a client-side comparison against locally-stored state can be bypassed, cleared, or simply unavailable. The hosted widget does both: it calls that endpoint, and also keeps its own fast local check (in localStorage) as a same-load fallback for when that call fails. |
cookiePolicyUrl | string | null | Same idea, for a separate cookie policy page, if the org maintains one distinct from their main privacy policy. null if not set. |
termsOfServiceUrl | string | null | Same idea, for the org's terms of service page. null if not set. |
purposes | array | The list of purposes this notice covers |
Only status = ACTIVE notices are ever returned by the public GET /notice endpoint — DRAFT notices are
invisible to your integration until published, and ARCHIVED ones aren't served either (though they remain
queryable by the org's admins for audit history).
noticeGroupKey
This is the field that trips people up, so it's worth being explicit: id identifies one specific version of a
notice. noticeGroupKey (plus language) identifies the logical document, independent of version.
Imagine you integrate once, hardcoding notice id=12 into your widget's config. The day the org edits and
republishes that notice, a new version takes over — id=13. Every website using your widget is now stuck
showing a stale, ARCHIVED notice forever, because nothing told it to look at id=13 instead.
noticeGroupKey solves this. You configure your widget once with the groupKey, not an id, and always
re-fetch GET /notice?groupKey=...&lang=... (as shown in Quickstart) rather than
caching a specific notice id.
Every page load, the widget calls GET /notice?groupKey=privacy-policy&lang=en — which resolves to "whichever
notice is currently ACTIVE for this groupKey+language" server-side. When the org publishes v3 next month, this
same call transparently starts returning the new version. Your integration code never has to change.
Why language matters too
One noticeGroupKey can have several simultaneously-ACTIVE versions — one per language:
| id | noticeGroupKey | language | version | status |
|---|---|---|---|---|
| 12 | privacy-policy | en | 2 | ACTIVE |
| 15 | privacy-policy | hi | 1 | ACTIVE |
Same logical document, different language variants, each independently versioned. Pass both groupKey and lang
— "the currently active privacy policy" isn't fully specified without knowing which language.
Multiple, unrelated notices per org
An org typically authors more than one notice — e.g. "privacy-policy" and "cookie-notice" are two separate,
independent noticeGroupKeys, each with their own version history. If your product needs to show more than one
kind of notice, you'll call GET /notice once per groupKey.
Purposes
Each notice lists one or more purposes — the individual things you're asking consent for (e.g. "Marketing Communications", "Product Analytics"), each with its own legal basis and retention period.
| Field | Type | Notes |
|---|---|---|
purposeCode | string | Stable machine key for this purpose (e.g. marketing) — use this as the key in purposeSelections when granting consent |
name / description | string | What to show in your UI |
dataCategories | { code, name }[] | Which data categories this purpose covers, already resolved to a human-readable name (e.g. { "code": "mobile", "name": "Mobile" }) — a managed vocabulary, not free text |
thirdParties | { name, description, category, country, privacyPolicyUrl }[] | Which external entities (payment processors, analytics vendors, etc.) this purpose's data is shared with, if any — resolved server-side the same way dataCategories is. Empty array if this purpose shares data with no one. Each entry's own privacyPolicyUrl (if set) is that specific third party's policy, distinct from the notice-level privacyPolicyUrl above, which is your own org's. |
legalBasis | enum | CONSENT, or one of DPDPA's Sec 7 "certain legitimate uses": VOLUNTARILY_PROVIDED_DATA, STATE_SUBSIDY_BENEFIT_SERVICE, LEGAL_COMPLIANCE, MEDICAL_EMERGENCY, PUBLIC_HEALTH, DISASTER_OR_PUBLIC_ORDER, EMPLOYMENT_PURPOSES |
retentionPeriodDays | number | How long this data is retained for this purpose |
mandatory | boolean | If true, your UI should render this toggle locked on — the principal can't opt out of it and still use your core service |
restrictedForMinors | boolean | If true, this purpose can never be granted for a minor principal, even with guardian consent on file (DPDPA Sec 9(3) — no targeted advertising/tracking directed at children). Grey out or hide this toggle for a minor rather than letting them select it — the server force-denies it silently either way, but showing an active-looking toggle that quietly does nothing is a bad UX cue. |
requiresReconsent | boolean | If true, this purpose is new or its terms materially changed since the version a returning visitor may have already decided on — computed once when the notice is published. If you're building a custom integration instead of using the hosted widget (which already handles this), a stored decision for a purpose with requiresReconsent: true must be treated as undecided (default-deny) rather than carried forward — see Versioning Notices for the full per-purpose reconciliation logic to replicate. |
dataCategories.name, not .codeDPDPA Section 5 requires your notice to itemize what personal data each purpose covers, in plain language — not
just the purpose's own name/description. dataCategories gives you that per purpose, already resolved server-side:
GET /api/v1/cmp/pii-categories (where category names live) is an admin-only, session-authenticated endpoint your
widget's API key can't call, so resolving codes to names client-side isn't possible — this field exists precisely
so you never need to. Render something like "Marketing Communications — uses your Email, Mobile" rather than
just the purpose name alone.
thirdParties, if present, alongside dataCategoriesSame reasoning as above, but for who the data goes to rather than what it is — Section 5 requires both.
GET /api/v1/cmp/third-parties (the org's registry, where these names/descriptions live) is likewise
admin-only, so thirdParties on each purpose is the resolved, ready-to-render form. Most purposes will have an
empty array — only render the line when it's non-empty, e.g. "Shared with: Razorpay, Google Analytics."
legalBasis = CONSENT purposes are the ones a visitor can actually toggle off — that's the whole point of asking.
Purposes on any other legal basis are typically shown as informational ("we process X because Y"), not as an
opt-in toggle, though mandatory is the field your UI logic should actually key off of. Unlike GDPR, DPDPA has no
open-ended "legitimate interests" basis — every non-CONSENT value here maps to one specific, narrow clause in
DPDPA Section 7, not a general business-justification catch-all. Pick whichever one actually matches why you're
processing that data; don't default to VOLUNTARILY_PROVIDED_DATA just because it's the closest thing to
GDPR's "contract" basis unless that's genuinely the ground that applies.
See the Notices API reference for the full request/response shapes.