Skip to main content

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.

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​

FieldTypeRequiredNotes
noticeIdnumber✅From Get Active Notice — always the current notice's id, never hardcoded
purposeSelectionsobject✅Map of purposeCode → boolean, one entry per purpose on the notice
methodstring✅Which channel consent came through — see Consent method values below
captureMethodstringHow 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:

FieldTypeNotes
choicesobjectWhat 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
preferenceCenterCodestringWhich preference center design the person used. Recorded on the consent record
surfacestringCOOKIE_BANNER, PREFERENCE_CENTER or OTHER. Recorded on the consent record
pageUrlstringThe 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"
}'

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

Mandatory purposes

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:

stateMeaning
GRANTEDConsent is in force for this purpose.
WITHDRAWNIt was granted, then withdrawn; withdrawnAt says when.
DECLINEDIt 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.


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​

FieldTypeRequiredNotes
noticeIdnumber✅
purposeCodestringOmit 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."


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.

FieldTypeRequiredNotes
reasonstringWhy 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 }

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​

ParamTypeRequired
noticeIdnumber✅
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.

Why check this server-side instead of just comparing versions yourself

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.


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​

ParamTypeRequiredNotes
pagenumberDefaults to 0
sizenumberDefaults 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​

FieldTypeRequiredNotes
noticeIdnumber✅The notice whose decision prompt was shown
methodstring✅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" }'
Only call this when a decision is actually being asked for

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.