Skip to main content

Notices API

Background reading: Consent Notices — read this first, especially the noticeGroupKey section, before integrating against this endpoint.

Get active notice​

GET /notice?groupKey={groupKey}&lang={lang}

Returns the currently ACTIVE notice — and all of its purposes — for the given noticeGroupKey and language.

Query parameters​

ParamTypeRequiredNotes
groupKeystring✅The notice's stable group key, e.g. "privacy-policy"
langstringDefaults to "en" if omitted
hoststringThe website the notice is for, e.g. www.example.com. See Legal links per website
curl "$CMP_BASE/notice?groupKey=privacy-policy&lang=en&host=www.example.com" \
-H "X-Org-Api-Key: $CMP_KEY"

Grievance officers​

grievanceOfficers lists the people designated as Grievance Officers in CMP Settings, with the contact details a notice has to publish under DPDPA: name, email and mobile (either of the last two can be null). It is empty when no officer is designated. The details come from each officer's user profile, so updating a profile updates every notice at once. The hosted banner shows the first officer's name and email, and the preferences panel lists every officer with their phone.

rightsUrl (where a person exercises their rights) and boardComplaintUrl (where to complain to the Data Protection Board) are two optional links. Add them if you have a page for people to exercise their rights or one about complaining to the Data Protection Board; a person normally uses your own grievance process first. They are the same for every website and are null until your organisation sets them in CMP Settings → Legal Links. The hosted banner shows them next to the policy links.

privacyPolicyUrl, cookiePolicyUrl and termsOfServiceUrl default to the organisation-wide links from CMP Settings. If a website has its own link for any of them (set under CMP Settings → Legal Links, in the per-website section), this response returns the website's link for that field and the organisation link for the others. That way a custom banner or a mobile app built on this API shows the right links without any extra call.

A browser request is matched to its website automatically from the page's origin. A server-side or mobile caller has no origin, so pass host yourself; without it you get the organisation-wide links. The same applies to GET /notice/{id}.

Response — 200 OK​

{
"entity": {
"id": 12,
"noticeGroupKey": "privacy-policy",
"language": "en",
"version": 2,
"title": "Our Privacy Notice",
"content": "We collect your email and mobile number to...",
"status": "ACTIVE",
"publishedAt": "2026-07-01T09:00:00.000+00:00",
"effectiveFrom": "2026-07-01T09:00:00.000+00:00",
"privacyPolicyUrl": "https://example.com/privacy-policy",
"privacyPolicyVersion": "2.0",
"cookiePolicyUrl": "https://example.com/cookie-policy",
"termsOfServiceUrl": "https://example.com/terms",
"grievanceOfficers": [
{ "name": "Asha Rao", "email": "grievance@example.com", "mobile": "+91 98765 43210" }
],
"purposes": [
{
"id": 8,
"purposeCode": "marketing",
"name": "Marketing Communications",
"description": "Send promotional emails and SMS",
"dataCategories": [
{ "code": "email", "name": "Email" },
{ "code": "mobile", "name": "Mobile" }
],
"thirdParties": [
{
"name": "Mailchimp",
"description": "Email delivery for marketing campaigns",
"category": "Email Marketing",
"country": "United States",
"privacyPolicyUrl": "https://mailchimp.com/legal/privacy/"
}
],
"legalBasis": "CONSENT",
"retentionPeriodDays": 365,
"mandatory": false
},
{
"id": 9,
"purposeCode": "analytics",
"name": "Product Analytics",
"description": "Understand how you use our product",
"dataCategories": [
{ "code": "email", "name": "Email" }
],
"thirdParties": [],
"legalBasis": "VOLUNTARILY_PROVIDED_DATA",
"retentionPeriodDays": 730,
"mandatory": true,
"restrictedForMinors": false,
"requiresReconsent": false
}
]
},
"warnings": [],
"errors": [],
"success": true
}
This shape is specific to the public API

orgId is omitted (your key already scopes every response to your org) and dataCategories replaces the raw categoryCodes array with resolved { code, name } pairs — see Consent Notices → Purposes for why. This response is a purpose-built view for the widget, not the same object shape returned by the admin dashboard's API.

Fields​

See the full field tables in Consent Notices and Purposes — this endpoint returns exactly those shapes.

Topics and preferences (purposes[].choices)​

A purpose can carry finer choices inside it. When it does, the purpose has a choices object (absent otherwise):

"choices": {
"topics": [
{ "code": "product_news", "defaultOptIn": true,
"texts": { "en": { "label": "Product news", "description": "New features and releases" } } }
],
"preferences": [
{ "code": "channel", "selectionType": "MULTI", "displayAs": "CHECKBOXES", "required": true,
"texts": { "en": { "label": "How should we contact you?" } },
"options": [
{ "code": "email", "isDefault": true, "texts": { "en": { "label": "Email" } } },
{ "code": "sms", "texts": { "en": { "label": "SMS" } } }
] }
]
}
FieldNotes
topics[]Yes or no choices. defaultOptIn is only a starting position shown to the person, never recorded as consent by itself
preferences[]Pick from a list. selectionType is SINGLE or MULTI; displayAs is BUTTONS, DROPDOWN, CHECKBOXES or RADIO; required means one option must be picked
textsPer language, label and description

Send the person's answers in the choices field of Grant consent.

Failure — 404 Not Found​

{
"warnings": [],
"errors": [{ "message": "Active consent notice not found", "code": 18002, "status": false }],
"success": false
}

Returned when no ACTIVE notice exists for the given groupKey/lang combination — either nothing has been published yet, or you've got a typo in groupKey/lang. Design your integration to handle this gracefully (e.g. skip rendering the banner, or fall back to a default) rather than treating it as a hard failure — it's a normal, expected state for a new org that hasn't published a notice yet.


Get notice by id​

GET /notice/{id}

Fetches a specific notice regardless of its current status (ACTIVE, superseded, etc) — for when you need to show exactly what a particular version said, not whatever is active right now. The main use case is a consent history / audit UI: a principal's stored consent record references a noticeId that may no longer be the active version for its noticeGroupKey, and Versioning Notices means the content really can differ between versions.

Don't use this to render your banner

This is for historical display only. Get active notice remains the correct call for deciding what to actually show a visitor and request consent for — always re-fetch by groupKey/lang, never hardcode an id, for that purpose.

Path parameters​

ParamTypeRequired
idnumber✅
curl "$CMP_BASE/notice/12" \
-H "X-Org-Api-Key: $CMP_KEY"

Response — 200 OK​

Same shape as Get active notice — including a notice whose status is no longer ACTIVE.

Failure — 404 Not Found​

Returned if id doesn't exist, or exists but belongs to a different org than your key resolves to.