Skip to main content

Preference Center API

The calls the hosted preference center page makes, for when you build your own page or need the same data on your backend. Designing the page itself (pages, sections, rules, domains) is done in the dashboard, see Designing your preference center.

Public calls below use the base URL and headers from the overview: X-Org-Api-Key, plus X-Principal-Token where marked. Server calls use /api/v1/server/cmp with your Secret key (see Server-side integration).

All responses use the usual { "entity": ..., "warnings": [], "errors": [], "success": true } envelope.

Public calls​

Get the published design​

GET /preference-center/schema?pc=<code>&lang=en

Org key only. Returns the published design of one preference center. pc is the center's code; leave it out for the org's default (or, on a custom domain that names a design, that design). lang limits the text overrides to one language. entity is null when nothing is published, in which case the page keeps its built-in look. The answer is cached for a few minutes and refreshed when you publish.

Get the visitor's context​

GET /preference-center/context

Org key only. Returns what the page needs for its rules that only the server knows: { "country": "IN" }, or null for country when it cannot be worked out. It says nothing about any person beyond the caller's own address.

Who am I​

GET /principals/me

Needs the principal token. Returns { "minor": false, "preferredLanguage": "en" }, which is all the page needs to decide what to show.

Profile questions​

GET /profile
PUT /profile

Needs the principal token. The questions your organisation asks (set up in the dashboard under Preference Centers → Profile fields), with the person's answers.

{
"entity": [
{
"code": "fld_8k2m1x",
"fieldType": "SELECT",
"required": false,
"active": true,
"sortOrder": 1,
"purposeCode": "marketing",
"options": ["daily", "weekly"],
"labels": { "en": { "label": "How often?" } },
"value": "weekly",
"editable": true
}
],
"success": true
}
FieldNotes
fieldTypeTEXT, LONG_TEXT, NUMBER (plain decimals only), DATE, EMAIL, PHONE, SELECT, CHECKBOX
purposeCodeWhen set, the answer can be saved only while that purpose is granted
editablefalse while that purpose has no consent. Clearing an answer is always allowed
valueThe person's answer, null when none

PUT /profile takes { "values": { "fld_8k2m1x": "daily", "fld_other": "" } }, a field code to an answer. A blank answer clears it. If any answer is refused (wrong type, not one of the options, purpose not granted) the whole save is refused and nothing is written; the error names the field. The reply is the updated list. A profile.updated webhook carries the codes that changed, never the answers.

Grant, withdraw, unsubscribe​

Grant consent accepts choices, preferenceCenterCode and surface for what the person answered inside purposes and where. Unsubscribe from everything withdraws every purpose the person can withdraw in one call.

Server calls​

All need your Secret key in X-Org-Api-Key and identify the person by the externalId you registered.

Read a person's topic and preference answers​

GET /api/v1/server/cmp/consent/preferences?externalId=user-4821&purposeCode=marketing
{
"entity": {
"granted": true,
"consentRecordId": 77,
"recordedAt": "2026-11-01T10:15:00.000+00:00",
"choices": {
"topics": { "product_news": true, "offers": false },
"preferences": { "channel": ["email"] }
}
},
"success": true
}

Answers are returned only while consent for the purpose is granted. After a denial or withdrawal, or for an unknown person, granted is false and choices is null.

Read and write a person's profile answers​

GET /api/v1/server/cmp/principals/profile?externalId=user-4821
PUT /api/v1/server/cmp/principals/profile?externalId=user-4821

Same shapes and same rules as the person's own /profile: the field's purpose needs consent, and values are checked by type.

List every code​

GET /api/v1/server/cmp/codes
GET /api/v1/server/cmp/codes?type=purposes

The notice, purpose and data category codes you can use, with the name each is known by. type is notices, purposes or dataCategories to get one list only.

{
"entity": {
"notices": [{ "code": "privacy-policy", "name": "Privacy policy", "status": "ACTIVE" }],
"purposes": [{ "code": "marketing", "name": "Marketing", "mandatory": false, "dataCategories": ["email"] }],
"dataCategories": [{ "code": "email", "name": "Email" }],
"guide": ["..."]
},
"success": true
}