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
}
| Field | Notes |
|---|---|
fieldType | TEXT, LONG_TEXT, NUMBER (plain decimals only), DATE, EMAIL, PHONE, SELECT, CHECKBOX |
purposeCode | When set, the answer can be saved only while that purpose is granted |
editable | false while that purpose has no consent. Clearing an answer is always allowed |
value | The 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
}