API: Banners | CMPStack docs

List every domain and its banner status (filterable)

GET/v1/banner

Needs: A signed-in panel session, sent as Authorization: Bearer <access token>.

Parameters
Name	Where	Type	What it is
status	query	"published" \| "draft"	Publish state.
layout	query	"bar" \| "modal" \| "popup"	Banner layout.
q	query	string	Case-insensitive search over name + hostname.

Responses
Status	Body	When
200	BannerSummaryDto[]

200 body · BannerSummaryDto[]
Field	Type	What it is
domainId required	string
hostname required	string
name required	string
published required	boolean
publishedAt required	string \| null
updatedAt required	string \| null
layout required	"bar" \| "modal" \| "popup"	Layout and colours for the list thumbnail and preview (from the config).
accent required	string
background required	string
foreground required	string
geoMode required	"custom" \| "eea" \| "all"
impressions required	number	Banners shown and the consent rate over the last 30 days, for this domain. `consentRate` is null when nothing has been shown yet.
consentRate required	number \| null
score required	number	Live compliance score (0–100) for this domain's banner: the same score the Compliance screen and the Domains list show.
overAllowance required	boolean	True when the workspace's plan does not cover this domain. Its banner is held unpublished, and publishing is refused until the plan allows more domains or another domain is removed.

Responses
Status	Body	When
200	string[]

Languages with built-in starter text

GET/v1/banner/locales

What the builder offers when adding a language, and the wording it pre-fills. Not a whitelist: any well-formed BCP-47 tag can be saved as a translation, this is only the set we ship text for.

Needs: A signed-in panel session, sent as Authorization: Bearer <access token>.

Responses
Status	Body	When
200	BannerLocaleDto[]

200 body · BannerLocaleDto[]
Field	Type	What it is
code required	string	BCP-47 tag, e.g. `de`.
englishName required	string	For an operator reading the list in English.
nativeName required	string	For a customer picking their own market's language.
content required	BannerTranslatedContentDto	Starter wording — a beginning, not a legal opinion. Editable like any other.
content.title required	string
content.description required	string
content.acceptLabel required	string
content.rejectLabel required	string
content.settingsLabel required	string
content.saveLabel required	string
content.policyUrl	string	This language's own policy page. Omitted = use the default language's.
categories required	BannerCategoryTextDto[]
categories[].id required	"necessary" \| "analytics" \| "marketing" \| "preferences"
categories[].label required	string
categories[].description required	string
optOut required	BannerOptOutDto	Starter wording for the US opt-out notice in this language.
optOut.title required	string
optOut.description required	string
optOut.optOutLabel required	string	The prominent action. Denies every sale/share category at once.
optOut.dismissLabel required	string	Dismiss without changing anything — processing continues, lawfully.
optOut.linkLabel required	string	The persistent link, which is the part the law actually requires. It stays on the page after the notice is gone, which is why it is not a banner label.
notice required	BannerNoticeDto	Starter label for the rest-of-world notice's one button.
notice.dismissLabel required	string

Ten banners to start from

GET/v1/banner/templates

Every one of them publishes with zero hard blocks and zero warnings, in every language it ships. Applying one is an ordinary config save.

Needs: A signed-in panel session, sent as Authorization: Bearer <access token>.

Responses
Status	Body	When
200	TemplateDto[]

200 body · TemplateDto[]
Field	Type	What it is
id required	string
name required	string
summary required	string
tone required	string
config required	BannerConfigDto
config.content required	BannerContentDto
config.style required	BannerStyleDto
config.targeting required	BannerTargetingDto
config.behavior required	BannerBehaviorDto
config.categories required	BannerCategoryDto[]
config.cookieDomain	string	Root domain for sharing the consent cookie across subdomains, e.g. `.example.com`. Must be a hostname.
config.hideBranding	boolean	Hide the "Powered by CMPStack" mark. Requires a plan that includes it; saving it on another plan returns 409.
config.optOut	BannerOptOutDto	The US opt-out notice's wording, shown only to visitors under the US opt-out rules. When it is absent, default wording is used.
config.notice	BannerNoticeDto	The rest-of-world notice's button. Optional; defaults to "OK".
config.customCss	string	Custom CSS for the banner. Requires a plan that includes custom CSS. Its length and content are checked when it is saved and again when it is served.
config.blocking	BlockingRuleDto[]	Third-party scripts held back until their category is allowed. At most 60.
config.vitals	boolean	Measure real-user performance on this site: LCP, INP and CLS per page view. Off unless switched on, because it loads one more small file on the visitor's page.
config.defaultLocale	string	The language `content` and `categories` are written in, and the one shown to any visitor whose language has no translation. Absent means `en`.
config.translations	BannerTranslationDto[]	The same banner in other languages, at most 40. The default language is not repeated here: it is `content`, and a translation for it is refused.
review required	ConfigReviewDto
review.blocks required	string[]	Rules that would refuse a publish.
review.warnings required	string[]	Rules that would lower the score.

Get a domain's banner config (defaults if unconfigured)

GET/v1/banner/{domainId}

Needs: A signed-in panel session, sent as Authorization: Bearer <access token>.

Parameters
Name	Where	Type	What it is
domainId required	path	string

Responses
Status	Body	When
200	BannerConfigResponseDto

200 body · BannerConfigResponseDto
Field	Type	What it is
domainId required	string
hostname required	string
name required	string
published required	boolean	True once the draft has been published at least once.
publishedAt required	string \| null	ISO timestamp of the last publish, or null if never published.
updatedAt required	string	ISO timestamp of the last draft save.
config required	BannerConfigDto	The working draft the builder edits.
config.content required	BannerContentDto
config.style required	BannerStyleDto
config.targeting required	BannerTargetingDto
config.behavior required	BannerBehaviorDto
config.categories required	BannerCategoryDto[]
config.cookieDomain	string	Root domain for sharing the consent cookie across subdomains, e.g. `.example.com`. Must be a hostname.
config.hideBranding	boolean	Hide the "Powered by CMPStack" mark. Requires a plan that includes it; saving it on another plan returns 409.
config.optOut	BannerOptOutDto	The US opt-out notice's wording, shown only to visitors under the US opt-out rules. When it is absent, default wording is used.
config.notice	BannerNoticeDto	The rest-of-world notice's button. Optional; defaults to "OK".
config.customCss	string	Custom CSS for the banner. Requires a plan that includes custom CSS. Its length and content are checked when it is saved and again when it is served.
config.blocking	BlockingRuleDto[]	Third-party scripts held back until their category is allowed. At most 60.
config.vitals	boolean	Measure real-user performance on this site: LCP, INP and CLS per page view. Off unless switched on, because it loads one more small file on the visitor's page.
config.defaultLocale	string	The language `content` and `categories` are written in, and the one shown to any visitor whose language has no translation. Absent means `en`.
config.translations	BannerTranslationDto[]	The same banner in other languages, at most 40. The default language is not repeated here: it is `content`, and a translation for it is refused.

Save a domain's banner draft

PUT/v1/banner/{domainId}

Needs: A signed-in panel session, sent as Authorization: Bearer <access token>.

Parameters
Name	Where	Type	What it is
domainId required	path	string

Request body · UpdateBannerDto
Field	Type	What it is
name	string
config required	BannerConfigDto
config.content required	BannerContentDto
config.style required	BannerStyleDto
config.targeting required	BannerTargetingDto
config.behavior required	BannerBehaviorDto
config.categories required	BannerCategoryDto[]
config.cookieDomain	string	Root domain for sharing the consent cookie across subdomains, e.g. `.example.com`. Must be a hostname.
config.hideBranding	boolean	Hide the "Powered by CMPStack" mark. Requires a plan that includes it; saving it on another plan returns 409.
config.optOut	BannerOptOutDto	The US opt-out notice's wording, shown only to visitors under the US opt-out rules. When it is absent, default wording is used.
config.notice	BannerNoticeDto	The rest-of-world notice's button. Optional; defaults to "OK".
config.customCss	string	Custom CSS for the banner. Requires a plan that includes custom CSS. Its length and content are checked when it is saved and again when it is served.
config.blocking	BlockingRuleDto[]	Third-party scripts held back until their category is allowed. At most 60.
config.vitals	boolean	Measure real-user performance on this site: LCP, INP and CLS per page view. Off unless switched on, because it loads one more small file on the visitor's page.
config.defaultLocale	string	The language `content` and `categories` are written in, and the one shown to any visitor whose language has no translation. Absent means `en`.
config.translations	BannerTranslationDto[]	The same banner in other languages, at most 40. The default language is not repeated here: it is `content`, and a translation for it is refused.

Responses
Status	Body	When
200	BannerConfigResponseDto

200 body · BannerConfigResponseDto
Field	Type	What it is
domainId required	string
hostname required	string
name required	string
published required	boolean	True once the draft has been published at least once.
publishedAt required	string \| null	ISO timestamp of the last publish, or null if never published.
updatedAt required	string	ISO timestamp of the last draft save.
config required	BannerConfigDto	The working draft the builder edits.
config.content required	BannerContentDto
config.style required	BannerStyleDto
config.targeting required	BannerTargetingDto
config.behavior required	BannerBehaviorDto
config.categories required	BannerCategoryDto[]
config.cookieDomain	string	Root domain for sharing the consent cookie across subdomains, e.g. `.example.com`. Must be a hostname.
config.hideBranding	boolean	Hide the "Powered by CMPStack" mark. Requires a plan that includes it; saving it on another plan returns 409.
config.optOut	BannerOptOutDto	The US opt-out notice's wording, shown only to visitors under the US opt-out rules. When it is absent, default wording is used.
config.notice	BannerNoticeDto	The rest-of-world notice's button. Optional; defaults to "OK".
config.customCss	string	Custom CSS for the banner. Requires a plan that includes custom CSS. Its length and content are checked when it is saved and again when it is served.
config.blocking	BlockingRuleDto[]	Third-party scripts held back until their category is allowed. At most 60.
config.vitals	boolean	Measure real-user performance on this site: LCP, INP and CLS per page view. Off unless switched on, because it loads one more small file on the visitor's page.
config.defaultLocale	string	The language `content` and `categories` are written in, and the one shown to any visitor whose language has no translation. Absent means `en`.
config.translations	BannerTranslationDto[]	The same banner in other languages, at most 40. The default language is not repeated here: it is `content`, and a translation for it is refused.

Read colours, a font and a logo off the domain's own home page

POST/v1/banner/{domainId}/brand

Fetched by our server with the same protections as domain verification, and only where robots.txt allows it. Only a suggestion: nothing is applied or published.

Needs: A signed-in panel session, sent as Authorization: Bearer <access token>.

Parameters
Name	Where	Type	What it is
domainId required	path	string

Responses
Status	Body	When
200	BrandSuggestionDto

200 body · BrandSuggestionDto
Field	Type	What it is
accent	string \| null
background	string \| null
foreground	string \| null
font	string \| null
logo	string \| null	For the preview only. Never rendered into a published banner.
sources required	object	Where each value came from, so a customer can disagree with a reason.
reason	string \| null	Why nothing could be read, when nothing could.

Describe how the banner should look, and get a previewable change

POST/v1/banner/{domainId}/describe

Style only — never wording, which is the part with legal consequences. The answer is checked against the banner rules and the publish checks before it is returned, and it is labelled as generated.

Needs: A signed-in panel session, sent as Authorization: Bearer <access token>.

Parameters
Name	Where	Type	What it is
domainId required	path	string

Request body · DescribeBannerDto
Field	Type	What it is
description required	string	How the banner should look, in your own words. Style only — the wording is never changed, because that is the part with legal consequences. Example: `"warm and minimal, matching our navy brand, not too shouty"`

Responses
Status	Body	When
200	StyleProposalDto
503	—	No provider is configured, or it declined

200 body · StyleProposalDto
Field	Type	What it is
style required	object	The style fields to change.
rationale required	string	One sentence on what was read from the description.
generated required	boolean	Always true. Shown as generated wherever it appears.
review required	ConfigReviewDto	What the change would mean at publish.
review.blocks required	string[]	Rules that would refuse a publish.
review.warnings required	string[]	Rules that would lower the score.

Publish the current draft, so visitors are shown it

POST/v1/banner/{domainId}/publish

Refused with 422 when the draft fails a hard-block compliance rule — no Reject button, pre-selected optional categories, no granular choice, scroll-as-consent. The body carries rule, field, fix and every blocked rule so the builder can take the customer to what needs changing. The draft is untouched.

Needs: A signed-in panel session, sent as Authorization: Bearer <access token>.

Parameters
Name	Where	Type	What it is
domainId required	path	string

Responses
Status	Body	When
201	BannerConfigResponseDto
422	—	The draft fails a hard-block compliance rule

201 body · BannerConfigResponseDto
Field	Type	What it is
domainId required	string
hostname required	string
name required	string
published required	boolean	True once the draft has been published at least once.
publishedAt required	string \| null	ISO timestamp of the last publish, or null if never published.
updatedAt required	string	ISO timestamp of the last draft save.
config required	BannerConfigDto	The working draft the builder edits.
config.content required	BannerContentDto
config.style required	BannerStyleDto
config.targeting required	BannerTargetingDto
config.behavior required	BannerBehaviorDto
config.categories required	BannerCategoryDto[]
config.cookieDomain	string	Root domain for sharing the consent cookie across subdomains, e.g. `.example.com`. Must be a hostname.
config.hideBranding	boolean	Hide the "Powered by CMPStack" mark. Requires a plan that includes it; saving it on another plan returns 409.
config.optOut	BannerOptOutDto	The US opt-out notice's wording, shown only to visitors under the US opt-out rules. When it is absent, default wording is used.
config.notice	BannerNoticeDto	The rest-of-world notice's button. Optional; defaults to "OK".
config.customCss	string	Custom CSS for the banner. Requires a plan that includes custom CSS. Its length and content are checked when it is saved and again when it is served.
config.blocking	BlockingRuleDto[]	Third-party scripts held back until their category is allowed. At most 60.
config.vitals	boolean	Measure real-user performance on this site: LCP, INP and CLS per page view. Off unless switched on, because it loads one more small file on the visitor's page.
config.defaultLocale	string	The language `content` and `categories` are written in, and the one shown to any visitor whose language has no translation. Absent means `en`.
config.translations	BannerTranslationDto[]	The same banner in other languages, at most 40. The default language is not repeated here: it is `content`, and a translation for it is refused.

Next groupConsent records

Banners

01List every domain and its banner status (filterable)

02Fonts a banner may be set in

03Languages with built-in starter text

04Ten banners to start from

05Get a domain's banner config (defaults if unconfigured)

06Save a domain's banner draft

07Read colours, a font and a logo off the domain's own home page

08Describe how the banner should look, and get a previewable change

09Publish the current draft, so visitors are shown it

List every domain and its banner status (filterable)

Fonts a banner may be set in

Languages with built-in starter text

Ten banners to start from

Get a domain's banner config (defaults if unconfigured)

Save a domain's banner draft

Read colours, a font and a logo off the domain's own home page

Describe how the banner should look, and get a previewable change

Publish the current draft, so visitors are shown it