Banner

The banner is the consent dialog shown to visitors. Each site has one banner configuration that controls its template, position, colors, text, and consent behavior.

Using React? The ConsentGate component lets you conditionally render content based on consent categories — no manual banner API calls needed.

GET

Get banner configuration

GET /sites/{id}/banner

Returns the current banner configuration for a site.

Path parameters

idstringrequired

Site ID (UUID)

Response fields

Field	Type	Description
`id`	string	Banner config ID
`siteId`	string	Parent site ID
`template`	string	Banner template: `floating`, `wide_bar`, or `modal`
`position`	string	Position on screen (e.g. `bottom_left`, `top`, `center`)
`colors`	object	Color overrides for `primary`, `background`, `text`, `acceptButton`, `rejectButton`
`textOverrides`	object	Custom text for `headline`, `body`, `acceptLabel`, `rejectLabel`, `preferencesLabel`
`logoUrl`	string	URL to a custom logo displayed in the banner
`privacyPolicyUrl`	string	Link to your privacy policy
`defaultBehavior`	string	`opt_in` (GDPR), `opt_out` (CCPA), or `no_banner`
`closeButtonBehavior`	string	`accept_all`, `reject_all`, or `dismiss`
`cookieExpirationDays`	integer	How long consent is remembered
`consentVersion`	integer	Incremented to re-prompt visitors after changes
`gcmExcludeGoogle`	boolean	Exclude Google services from consent blocking
`shopifyIntegration`	boolean	Enable Shopify-specific features

curl https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/banner \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7"

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/banner`,
  { headers: { Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7' } },
);
const banner = await res.json();

import requests

res = requests.get(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/banner",
    headers={"Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7"},
)
banner = res.json()

Response 200

{
  "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "siteId": "e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789",
  "template": "floating",
  "position": "bottom_left",
  "colors": {
    "primary": "#4F46E5",
    "background": "#FFFFFF",
    "text": "#1F2937",
    "acceptButton": "#4F46E5",
    "rejectButton": "#6B7280"
  },
  "textOverrides": {
    "headline": "We value your privacy",
    "body": "We use cookies to improve your experience.",
    "acceptLabel": "Accept all",
    "rejectLabel": "Reject all",
    "preferencesLabel": "Manage preferences"
  },
  "logoUrl": null,
  "privacyPolicyUrl": "https://example.com/privacy",
  "defaultBehavior": "opt_in",
  "closeButtonBehavior": "reject_all",
  "cookieExpirationDays": 365,
  "consentVersion": 1,
  "blockingRules": null,
  "gcmExcludeGoogle": false,
  "shopifyIntegration": false,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-03-20T14:22:00.000Z"
}

PATCH

Update banner configuration

PATCH /sites/{id}/banner

Partially updates the banner configuration. Only include the fields you want to change.

Path parameters

idstringrequired

Site ID (UUID)

Request body

templatestring

Banner template: floating, wide_bar, or modal

positionstring

Position: bottom_left, bottom_right, top_left, top_right, bottom, top, center

colorsobject

Color overrides with keys: primary, background, text, acceptButton, rejectButton

textOverridesobject

Text overrides with keys: headline, body, acceptLabel, rejectLabel, preferencesLabel

privacyPolicyUrlstring

Link to your privacy policy page

defaultBehaviorstring

Consent behavior: opt_in (GDPR), opt_out (CCPA), or no_banner

closeButtonBehaviorstring

When user clicks X: accept_all, reject_all, or dismiss

cookieExpirationDaysinteger

Days until consent cookie expires

Error responses

Status	Description
`404`	Site not found
`422`	Invalid field values

curl -X PATCH https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/banner \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "wide_bar",
    "position": "bottom",
    "colors": {
      "primary": "#2563EB",
      "acceptButton": "#2563EB"
    }
  }'

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/banner`,
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      template: 'wide_bar',
      position: 'bottom',
      colors: {
        primary: '#2563EB',
        acceptButton: '#2563EB',
      },
    }),
  },
);
const banner = await res.json();

import requests

res = requests.patch(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/banner",
    headers={
        "Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7",
        "Content-Type": "application/json",
    },
    json={
        "template": "wide_bar",
        "position": "bottom",
        "colors": {
            "primary": "#2563EB",
            "acceptButton": "#2563EB",
        },
    },
)
banner = res.json()

Response 200

Returns the full updated banner configuration (same shape as GET response).