Consent API
Background reading: Consent Records.
Every endpoint here requires 🔒 principal token — an X-Principal-Token header identifying the principal (see
Authentication). There is no principalId field in
any request body or query string; the principal is derived entirely from the token, so it can't be spoofed by
supplying a different value.
Grant consent​
POST /consent/grant
Records a principal's purpose-level consent decision against a specific notice. Always creates a new consent record — see Consent Records → Granting vs. withdrawing.
Request body​
| Field | Type | Required | Notes |
|---|---|---|---|
noticeId | number | ✅ | From Get Active Notice — always the current notice's id, never hardcoded |
purposeSelections | object | ✅ | Map of purposeCode → boolean, one entry per purpose on the notice |
method | string | ✅ | Which channel consent came through — see Consent method values below |
captureMethod | string | How consent was physically captured ("CHECKBOX", "TOGGLE_SWITCH", "BUTTON_CLICK", ...) — a separate axis from method. Omit it and the server infers a reasonable default from method |
Optional fields for the preference center:
| Field | Type | Notes |
|---|---|---|
choices | object | What the person answered inside each purpose: purposeCode → { "topics": { topicCode: boolean }, "preferences": { preferenceCode: [optionCode, ...] } }. Codes come from the notice's purposes[].choices. Unknown codes are refused; answers for a purpose that is not granted are dropped. The stored answers are fingerprinted (SHA-256) on the consent record as proof of what was chosen |
preferenceCenterCode | string | Which preference center design the person used. Recorded on the consent record |
surface | string | COOKIE_BANNER, PREFERENCE_CENTER or OTHER. Recorded on the consent record |
pageUrl | string | The page the decision was made on |
{
"noticeId": 12,
"purposeSelections": { "marketing": true },
"method": "WIDGET",
"choices": {
"marketing": {
"topics": { "product_news": true, "offers": false },
"preferences": { "channel": ["email"], "frequency": ["weekly"] }
}
}
}
curl -X POST "$CMP_BASE/consent/grant" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"noticeId": 12,
"purposeSelections": { "marketing": false, "analytics": true },
"method": "WIDGET",
"captureMethod": "TOGGLE_SWITCH"
}'
Consent method values​
method accepts "WIDGET" (used by the hosted widget), "API", "MANUAL", or
any of the following, for integrations collecting consent through another touchpoint (used identically on
Record a notice view's method field, so both stay comparable in the admin
dashboard's channel reporting):
WEB_BANNER, WEB_FORM, CUSTOMER_PORTAL, MOBILE_APP, DESKTOP_APP, EMBEDDED_WIDGET, EMAIL,
SMS, WHATSAPP, CALL_CENTER, IVR, PAPER_FORM, IN_PERSON, KIOSK, POS, CHATBOT, QR_CODE,
IMPORT, OTHER
Even if you omit a mandatory: true purpose's code from purposeSelections (or send false for it), it's up to
your UI to prevent that — the API itself doesn't currently force mandatory purposes to true server-side. Render
mandatory toggles as locked-on in your widget so this can't happen from the UI, and don't rely on server-side
enforcement of this rule today.
Response — 201 Created​
{
"entity": {
"id": 77,
"orgId": 1,
"status": "ACTIVE",
"consentMethod": "WIDGET",
"captureMethod": "TOGGLE_SWITCH",
"ipAddress": "203.0.113.4",
"userAgent": "Mozilla/5.0 ...",
"timestamp": "2026-07-04T10:15:00.000+00:00",
"sha256Checksum": "a1b2c3d4e5f6...",
"privacyPolicyVersionAtConsent": "2.0",
"withdrawnAt": null,
"purposeRecords": [
{ "id": 150, "purposeId": 33, "purposeCode": "marketing", "purposeName": "Marketing", "status": "DENIED", "state": "DECLINED", "withdrawnAt": null },
{ "id": 151, "purposeId": 34, "purposeCode": "analytics", "purposeName": "Analytics", "status": "GRANTED", "state": "GRANTED", "withdrawnAt": null }
]
},
"warnings": [],
"errors": [],
"success": true
}
Each entry in purposeRecords corresponds to one purpose on the notice, and says which one (purposeId, purposeCode,
purposeName) so you can show "you agreed to X, declined Y" without a second lookup. state is the one word to display:
state | Meaning |
|---|---|
GRANTED | Consent is in force for this purpose. |
WITHDRAWN | It was granted, then withdrawn; withdrawnAt says when. |
DECLINED | It was never granted; the person said no when they decided. |
status keeps the older two-value view (GRANTED or DENIED); a withdrawn purpose and a declined one are both DENIED
there, so use state to tell them apart. The record's own timestamp (also returned as consentGivenAt) is when consent was
given and never changes; withdrawnAt on the record is when it was withdrawn, null while it is still active.
privacyPolicyVersionAtConsent is a frozen snapshot of the org's privacyPolicyVersion (see
Notices → Fields) at the moment this record was created — null if the
org hadn't set one yet. You don't need to do anything with it yourself; it's what Check consent status
below compares against the org's current version to compute requiresPrivacyPolicyReconsent.
Failure — 500 Internal Server Error​
{ "warnings": [], "errors": [{ "message": "Notice not found", "code": 18000, "status": false }], "success": false }
Common causes: noticeId doesn't exist / belongs to a different org, or the principal is a minor with no guardian
registered (see Handling Minors). If noticeId, purposeSelections, or method is
missing entirely, you'll instead get a message like "Please specify which notice you're responding to.",
"Please include your choice for at least one purpose.", or "Please specify how this consent is being recorded (e.g. through our widget or your own form)." — all three are written to be shown to the data principal directly,
unlike most other 18000 messages on this page.
Failure — 401 Unauthorized (no envelope)​
Missing, invalid, or expired X-Principal-Token — mint a fresh one via Issue Token
and retry.
Withdraw consent​
POST /consent/withdraw
Finds the principal's most recent consent record for this notice and withdraws it — either entirely, or one purpose at a time.
Request body​
| Field | Type | Required | Notes |
|---|---|---|---|
noticeId | number | ✅ | |
purposeCode | string | Omit to withdraw the entire notice's consent (all purposes). Supply a specific purposeCode to withdraw just that one purpose, leaving the others as they were |
Whole-notice withdraw (omit purposeCode):
curl -X POST "$CMP_BASE/consent/withdraw" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "noticeId": 12 }'
Single-purpose withdraw — e.g. the principal wants to opt out of marketing while keeping analytics granted:
curl -X POST "$CMP_BASE/consent/withdraw" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "noticeId": 12, "purposeCode": "marketing" }'
To withdraw a purpose only for now, add snoozeUntil (an ISO date such as "2026-12-01" or date-time, in the future and at most 365 days away,
and only together with purposeCode). The purpose is withdrawn as usual, and from that date it counts as undecided again so you can ask again:
its state becomes UNDECIDED, the server consent check answers
SNOOZE_ENDED, and a consent.snooze_ended webhook is sent. Until that date it reads as withdrawn.
This flips just that purpose's purposeRecords entry status to DENIED and its state to WITHDRAWN, with withdrawnAt set. The overall consent record itself is
only marked WITHDRAWN once every purpose on it has ended up DENIED this way — as long as at least one purpose
is still GRANTED, Check Consent Status keeps returning the record as the current state
for this notice, just with that one purpose's purposeRecords entry showing DENIED.
Response — 200 OK​
{ "entity": true, "warnings": [], "errors": [], "success": true }
Failure — 500 Internal Server Error​
Returned if no existing consent record is found for this principal/notice pair to withdraw, or if purposeCode
doesn't match any purpose on that consent record. If noticeId itself is missing you'll get
"Please specify which notice you're withdrawing consent for." instead — always check noticeId is present on
this call the same way it is on Grant Consent; omitting it isn't a safe way to "withdraw
everything."
Import historical consent​
POST /api/v1/server/cmp/consent/import (Secret key)
Backfills consent you collected in an older system, up to 500 records per request. Each record is checked and saved on its own: one bad record never stops the others, and the answer lists the result of every record by its position.
{ "records": [ { "externalId": "cust-1", "email": "asha@example.com", "name": "Asha", "noticeGroupKey": "privacy-policy", "language": "en",
"noticeVersion": 2, "status": "ACTIVE", "timestamp": "2024-01-15T10:30:00Z", "purposeSelections": { "marketing": true } } ] }
{ "entity": [ { "index": 0, "ok": true, "error": null } ], "success": true }
The notice, language and version must already exist, status is ACTIVE or WITHDRAWN, and timestamp is the original ISO-8601 time.
Imported consents keep their original time, are marked as imported in the audit trail, and send no webhook and get no receipt, so your
automations react to consent happening now and not to history being loaded.
Unsubscribe from everything​
POST /consent/unsubscribe-all
Withdraws, in one step, every purpose the person is allowed to withdraw, on every notice where they still have something granted. Mandatory purposes are not consent and stay as they are.
| Field | Type | Required | Notes |
|---|---|---|---|
reason | string | Why the person is leaving. Up to 200 characters, kept in the audit trail. The body itself may be omitted |
curl -X POST "$CMP_BASE/consent/unsubscribe-all" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "reason": "Too many emails" }'
Response — 200 OK​
entity is the number of notices that had something withdrawn. It is 0 when the person had nothing left to
withdraw, so calling it twice is safe. A consent.unsubscribed_all webhook is sent when
anything changed.
{ "entity": 2, "warnings": [], "errors": [], "success": true }
Check consent status​
GET /consent/status?noticeId={noticeId}
Reads the current effective consent state — useful for showing "you have already consented" / "you have withdrawn" messaging, or deciding whether to show the banner at all.
Query parameters​
| Param | Type | Required |
|---|---|---|
noticeId | number | ✅ |
curl "$CMP_BASE/consent/status?noticeId=12" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN"
Response — 200 OK​
Same shape as the Grant Consent response, plus one extra field: requiresPrivacyPolicyReconsent
(boolean). This is computed fresh on every call, server-side, by comparing the record's own
privacyPolicyVersionAtConsent against the org's current privacyPolicyVersion — true only when both are
actually set and they differ. false covers every other case: the org has never set a version, or the record's
own version still matches the current one.
{
"entity": {
"id": 77,
"status": "ACTIVE",
"...": "... same fields as Grant Consent's response ...",
"privacyPolicyVersionAtConsent": "1.0",
"requiresPrivacyPolicyReconsent": true,
"expired": false,
"expiresAt": "2027-10-13T10:15:00.000+00:00"
},
"warnings": [],
"errors": [],
"success": true
}
expired and expiresAt apply the banner's consent expiry setting (Cookie Manager, Banner step) to the website the
consent was given on, or the default banner's setting if that website has none. expired is true once the consent is
older than that many days, so an API or mobile integration re-asks on the same schedule the hosted banner does. Both are
false / null when no expiry is configured.
Get Active Notice already returns the org's current
privacyPolicyVersion, so you could compare it against a version you stored client-side yourself when the
principal last consented — that's exactly what the hosted widget does, as a fast
local check that doesn't need this extra round trip. But client-stored state can be cleared, never set in the
first place, or simply isn't available to you at all if you're not the widget (a custom integration, a mobile
app). requiresPrivacyPolicyReconsent is the authoritative answer, computed from the principal's own consent
record rather than anything you supply — call this endpoint rather than relying on a local comparison alone if
your integration needs to be sure.
Failure — 404 Not Found​
Returned if no consent record exists yet for this principal/notice pair — treat this the same as "not yet consented," and show the banner.
List my consent records​
GET /consent/records
Lets a principal see their current consent state across every notice they've ever consented to, in one call —
useful for a "privacy dashboard" / "manage your consents" screen, without having to know every noticeId up front
and calling Check consent status once per notice.
This returns one entry per distinct notice — the latest consent record for that notice, reflecting whatever withdrawals have been applied — not the principal's full grant/withdraw history. If you need the full history of every consent event for audit purposes, that's an admin-facing capability, not available on this endpoint.
Query parameters​
| Param | Type | Required | Notes |
|---|---|---|---|
page | number | Defaults to 0 | |
size | number | Defaults to 20 |
curl "$CMP_BASE/consent/records?page=0&size=20" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN"
Response — 200 OK​
{
"entity": {
"content": [
{
"id": 77,
"orgId": 1,
"status": "ACTIVE",
"consentMethod": "WIDGET",
"timestamp": "2026-07-04T10:15:00.000+00:00",
"purposeRecords": [
{ "id": 150, "status": "DENIED" },
{ "id": 151, "status": "GRANTED" }
]
}
],
"number": 0,
"size": 20,
"totalElements": 1,
"totalPages": 1
},
"warnings": [],
"errors": [],
"success": true
}
Scoped strictly to the calling X-Principal-Token's own principal — there's no way to list another principal's
consent records, or every principal's records across the org (that's admin-facing only).
Record a notice view​
POST /notice/viewed
Records that a notice's decision prompt was actually shown to the principal — not merely that Get Active Notice was fetched, which also happens on every page load for an already-decided returning visitor whose banner never renders at all. This is purely an analytics signal: it feeds the admin dashboard's consent-conversion reporting (views vs. actual submissions, per channel) and has no effect on the principal's own consent state.
If you're using the hosted widget, this is called for you automatically at exactly the right moment — you don't need to call it yourself. It's documented here for custom/headless integrations that want their own banner's impressions reflected in the same reporting.
Request body​
| Field | Type | Required | Notes |
|---|---|---|---|
noticeId | number | ✅ | The notice whose decision prompt was shown |
method | string | ✅ | Same taxonomy as Grant Consent's method — use the same value here that you'll send when the visitor actually decides, so Views and Submissions line up per channel in the admin dashboard's conversion reporting |
curl -X POST "$CMP_BASE/notice/viewed" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "noticeId": 12, "method": "WIDGET" }'
Don't call this on every page load — only when your UI is genuinely about to show (or just showed) the visitor a decision prompt, whether that's a first-time banner or a re-consent prompt for a changed purpose. Calling it for an already-decided visitor whose banner stays hidden would inflate "views" without a corresponding opportunity to convert, making the resulting conversion-rate reporting meaningless.
Response — 200 OK​
{ "entity": true, "warnings": [], "errors": [], "success": true }
Failure — 500 Internal Server Error​
Returned if noticeId doesn't exist or belongs to a different org, or if noticeId/method is missing entirely.
Unlike the DP-facing messages elsewhere on this page, these are plain developer-facing text ("noticeId is required" / "method is required") — this endpoint is a fire-and-forget analytics signal your own code calls,
never something a visitor sees the result of.