Skip to main content

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​

FieldTypeNotes
idnumberSpecific to one version — see noticeGroupKey below for why you shouldn't hardcode this
noticeGroupKeystringThe stable identifier for "this logical notice" — see below
languagestringISO-ish language code (en, hi, ta, ...)
versionnumberIncrements every time this groupKey+language is republished
titlestringBanner headline
contentstringMarkdown-authored body text
statusenumDRAFT (being authored, not yet visible to the public API), ACTIVE (currently live), ARCHIVED (superseded by a newer version)
privacyPolicyUrlstring | nullA 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.
privacyPolicyVersionstring | nullA 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.
cookiePolicyUrlstring | nullSame idea, for a separate cookie policy page, if the org maintains one distinct from their main privacy policy. null if not set.
termsOfServiceUrlstring | nullSame idea, for the org's terms of service page. null if not set.
purposesarrayThe 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:

idnoticeGroupKeylanguageversionstatus
12privacy-policyen2ACTIVE
15privacy-policyhi1ACTIVE

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.

FieldTypeNotes
purposeCodestringStable machine key for this purpose (e.g. marketing) — use this as the key in purposeSelections when granting consent
name / descriptionstringWhat 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.
legalBasisenumCONSENT, 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
retentionPeriodDaysnumberHow long this data is retained for this purpose
mandatorybooleanIf true, your UI should render this toggle locked on — the principal can't opt out of it and still use your core service
restrictedForMinorsbooleanIf 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.
requiresReconsentbooleanIf 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.
Render dataCategories.name, not .code

DPDPA 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.

Render thirdParties, if present, alongside dataCategories

Same 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."

Rendering purposes

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.