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
| Param | Type | Required | Notes |
|---|---|---|---|
groupKey | string | ✅ | The notice's stable group key, e.g. "privacy-policy" |
lang | string | Defaults to "en" if omitted | |
host | string | The 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.
Rights and Data Protection Board links
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.
Legal links per website
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
}
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" } } }
] }
]
}
| Field | Notes |
|---|---|
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 |
texts | Per 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.
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
| Param | Type | Required |
|---|---|---|
id | number | ✅ |
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.