> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cookiechimp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update consent banner

> Update a consent banner's content, appearance or targeting. Set
`enabled` to `true` to make it live.




## OpenAPI

````yaml put /consent-banners/{id}
openapi: 3.1.0
info:
  title: CookieChimp API
  description: |
    API for CookieChimp.com.

    ## Request bodies

    Resource endpoints expect the resource wrapped under its own key, e.g.
    `{"category": {"name": "Analytics"}}` rather than a bare object.
    `PUT /password` wraps in `user`. Two endpoints take their body unwrapped:
    `POST /auth`, which takes `email` and `password` at the top level, and
    `POST /consent-banners/from-template`, which takes `jurisdiction_id` —
    a selector for which template to build from, not an attribute of the
    banner it creates.

    ## Response envelopes

    Listing endpoints — including `GET /groups` and `GET /accounts` — return
    `{"pagination": {...}, "data": [...]}`. `GET /banner-templates` is the
    exception: it returns `{"data": [...]}` with no pagination, being a fixed
    catalogue rather than a collection of the account's records.
    Most single-resource endpoints
    return `{"data": {...}}`; a single group or account is returned unwrapped.
    Resource-deletion endpoints return `{"message": "..."}`; `DELETE /auth`
    returns an empty object.
  version: 1.2.0
servers:
  - url: https://cookiechimp.com/api/v1
security:
  - authorization: []
paths:
  /consent-banners/{id}:
    put:
      tags:
        - Consent Banners
      summary: Update consent banner
      description: |
        Update a consent banner's content, appearance or targeting. Set
        `enabled` to `true` to make it live.
      operationId: updateConsentBanner
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/id'
      requestBody:
        description: Consent banner to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentBannerUpdateRequest'
      responses:
        '200':
          description: Updated consent banner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentBannerResponse'
        '400':
          $ref: '#/components/responses/AmbiguousAccount'
        '401':
          $ref: '#/components/responses/AccountTokenRequired'
        '403':
          $ref: '#/components/responses/AccountAdminRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    account_id:
      name: account_id
      in: query
      description: |
        Which account to act on, as the account's API id. Only meaningful for a
        user API key, which may reach several accounts — an account key already
        identifies exactly one and ignores this.

        Accepted by the endpoints that declare it; others act on the account the
        key resolves to on its own.

        Optional for reads, where it narrows the request to that account.
        Required for writes that declare it when the key can reach more than one
        account: without it the request would act on an account it picked rather
        than one you named, so it is refused with a `400`.
      required: false
      schema:
        type: string
    id:
      name: id
      in: path
      description: ID of the resource
      required: true
      schema:
        type: string
  schemas:
    ConsentBannerUpdateRequest:
      type: object
      properties:
        consent_banner:
          $ref: '#/components/schemas/ConsentBannerUpdate'
      required:
        - consent_banner
      example:
        consent_banner:
          name: EU banner
          consent_title: We use cookies
          consent_mode: opt_in
          target_type: selected_countries
          target_countries:
            - DE
            - FR
    ConsentBannerResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ConsentBanner'
    ConsentBannerUpdate:
      description: |
        Everything a banner accepts on update, including its translations.
      allOf:
        - $ref: '#/components/schemas/ConsentBannerWrite'
        - type: object
          properties:
            banner_languages_attributes:
              type: object
              description: >
                Create, update or discard translations. Not accepted when
                creating a

                banner — add them by updating it, which is where the account's

                language entitlement is enforced.


                Keys are arbitrary indices. Omit `id` to add a translation; pass
                the

                `id` from the banner's `translations` array to change an
                existing

                one, and set `discarded_at` to remove it.
              additionalProperties:
                type: object
                description: >
                  An entry without an `id` creates a translation and must name
                  its

                  `language_code`; an entry with one may send only the fields it

                  changes.
                anyOf:
                  - required:
                      - id
                  - required:
                      - language_code
                properties:
                  id:
                    type: string
                    description: From the banner's `translations` array
                  language_code:
                    type: string
                    description: ISO 639-1 code
                  consent_title:
                    type:
                      - string
                      - 'null'
                  consent_description:
                    type:
                      - string
                      - 'null'
                  banner_accept_btn_text:
                    type:
                      - string
                      - 'null'
                  banner_accept_necessary_btn_text:
                    type:
                      - string
                      - 'null'
                  banner_preferences_btn_text:
                    type:
                      - string
                      - 'null'
                  settings_title:
                    type:
                      - string
                      - 'null'
                  settings_description:
                    type:
                      - string
                      - 'null'
                  privacy_policy_url:
                    type:
                      - string
                      - 'null'
                  save_preferences_btn_text:
                    type:
                      - string
                      - 'null'
                  consent_additional_description:
                    type:
                      - string
                      - 'null'
                  banner_footer_content:
                    type:
                      - string
                      - 'null'
                  settings_more_info_title:
                    type:
                      - string
                      - 'null'
                  settings_more_info:
                    type:
                      - string
                      - 'null'
                  do_not_sell_title:
                    type:
                      - string
                      - 'null'
                  do_not_sell_description:
                    type:
                      - string
                      - 'null'
                  preferences_accept_btn_text:
                    type:
                      - string
                      - 'null'
                  preferences_accept_necessary_btn_text:
                    type:
                      - string
                      - 'null'
                  discarded_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: Set to remove this translation
    ConsentBanner:
      description: |
        Every setting the update endpoint accepts, plus the read-only fields
        below — the response is derived from the same list the API permits, so a
        banner can be read, edited and sent back unchanged.
      allOf:
        - $ref: '#/components/schemas/ConsentBannerWrite'
        - type: object
          properties:
            id:
              type: string
              readOnly: true
            name:
              type: string
            enabled:
              type: boolean
            enable_tcf:
              type: boolean
            force_consent:
              type: boolean
            consent_mode:
              type: string
            consent_duration_days:
              type: integer
            consent_layout:
              type: string
            consent_position:
              type: string
            preferences_control_level:
              type: string
            dark_mode:
              type: string
            language_autodetect:
              type: string
            revision:
              type: integer
              readOnly: true
              description: Bumped when a change requires visitors to consent again
            translations:
              type: array
              readOnly: true
              description: >
                The banner's translations, each with its localized copy
                alongside

                its `id` — so a client can read what it is allowed to write
                rather

                than overwriting fields it cannot see. The `id` is what you send

                back in `banner_languages_attributes` to update or discard one.
              items:
                type: object
                properties:
                  id:
                    type: string
                  language_code:
                    type: string
                    description: ISO 639-1 code
                  consent_title:
                    type:
                      - string
                      - 'null'
                  consent_description:
                    type:
                      - string
                      - 'null'
                  consent_additional_description:
                    type:
                      - string
                      - 'null'
                  banner_accept_btn_text:
                    type:
                      - string
                      - 'null'
                  banner_accept_necessary_btn_text:
                    type:
                      - string
                      - 'null'
                  banner_preferences_btn_text:
                    type:
                      - string
                      - 'null'
                  banner_footer_content:
                    type:
                      - string
                      - 'null'
                  settings_title:
                    type:
                      - string
                      - 'null'
                  settings_description:
                    type:
                      - string
                      - 'null'
                  settings_more_info_title:
                    type:
                      - string
                      - 'null'
                  settings_more_info:
                    type:
                      - string
                      - 'null'
                  privacy_policy_url:
                    type:
                      - string
                      - 'null'
                  do_not_sell_title:
                    type:
                      - string
                      - 'null'
                  do_not_sell_description:
                    type:
                      - string
                      - 'null'
                  preferences_accept_btn_text:
                    type:
                      - string
                      - 'null'
                  preferences_accept_necessary_btn_text:
                    type:
                      - string
                      - 'null'
                  save_preferences_btn_text:
                    type:
                      - string
                      - 'null'
            created_at:
              type: string
              format: date-time
              readOnly: true
            updated_at:
              type: string
              format: date-time
              readOnly: true
      example:
        id: ban1
        name: EU banner
        enabled: true
        enable_tcf: false
        force_consent: false
        consent_mode: opt_in
        consent_duration_days: 180
        consent_layout: box
        consent_position: bottom_center
        consent_title: We use cookies
        consent_description: We use cookies to improve your experience.
        privacy_policy_url: https://example.com/privacy
        preferences_control_level: category_and_services
        dark_mode: light
        language_autodetect: document
        revision: 2
        target_type: selected_countries
        target_countries:
          - DE
          - FR
        target_us_states: []
        target_canadian_regions: []
        translations:
          - id: trn1
            language_code: de
          - id: trn2
            language_code: fr
        created_at: '2023-01-05T10:15:30Z'
        updated_at: '2023-02-01T08:00:00Z'
    Error:
      type: object
      description: |
        The standard error envelope, used for authentication, authorization,
        pagination and not-found errors.
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
      example:
        errors:
          - code: 401
            message: Invalid API Key
    ValidationError:
      type: object
      description: |
        Returned when a create or update fails validation. Each entry carries a
        single human-readable `error` string.
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
      example:
        errors:
          - error: Name can't be blank
    ConsentBannerWrite:
      description: >
        Every setting the banner designer exposes, plus whether the banner is

        live. Creating a banner uses ConsentBannerSettings instead, which is
        this

        same set without `enabled`.
      allOf:
        - $ref: '#/components/schemas/ConsentBannerSettings'
        - type: object
          properties:
            enabled:
              type: boolean
              description: Whether the banner is live.
    ConsentBannerSettings:
      type: object
      description: |
        Every setting the banner designer exposes. The response returns the same
        set, so a banner can be read, edited and sent back unchanged. Fields the
        database leaves nullable are declared nullable here too — the response
        returns null for unset copy, and the same shape has to be sendable back.
      properties:
        banner_accept_btn_text:
          type:
            - string
            - 'null'
        banner_accept_necessary_btn_text:
          type:
            - string
            - 'null'
        banner_footer_content:
          type:
            - string
            - 'null'
        banner_preferences_btn_text:
          type:
            - string
            - 'null'
        btn_border_radius:
          type: string
        consent_additional_description:
          type:
            - string
            - 'null'
        consent_button_placement:
          type: string
        consent_description:
          type:
            - string
            - 'null'
        consent_duration_days:
          type: integer
          description: How long a visitor's choice is remembered
        consent_layout:
          type: string
          description: e.g. `box`, `bar`
        consent_mode:
          type: string
          description: e.g. `opt_in`, `opt_out`
        consent_position:
          type: string
          description: e.g. `bottom_center`
        consent_title:
          type:
            - string
            - 'null'
        dark_mode:
          type: string
          description: e.g. `light`, `dark`, `auto`
        do_not_sell_description:
          type:
            - string
            - 'null'
        do_not_sell_title:
          type:
            - string
            - 'null'
        enable_banner_footer:
          type: boolean
        enable_tcf:
          type: boolean
          description: Whether the banner runs in IAB TCF mode
        equal_weight_buttons:
          type: boolean
        floating_preferences_icon_position:
          type: string
        force_consent:
          type: boolean
          description: Whether the page is blocked until the visitor chooses
        language_autodetect:
          type: string
        logo_url_dark:
          type:
            - string
            - 'null'
        logo_url_light:
          type:
            - string
            - 'null'
        modal_border_radius:
          type: string
        name:
          type: string
        preferences_accept_btn_text:
          type:
            - string
            - 'null'
        preferences_accept_necessary_btn_text:
          type:
            - string
            - 'null'
        preferences_control_level:
          type: string
          description: How granular the preferences modal is
        privacy_policy_url:
          type:
            - string
            - 'null'
        save_preferences_btn_text:
          type:
            - string
            - 'null'
        settings_description:
          type:
            - string
            - 'null'
        settings_layout:
          type: string
        settings_more_info:
          type:
            - string
            - 'null'
        settings_more_info_title:
          type:
            - string
            - 'null'
        settings_position_x:
          type: string
        settings_title:
          type:
            - string
            - 'null'
        show_banner_accept_btn:
          type: boolean
        show_banner_accept_necessary_btn:
          type: boolean
        show_banner_close_btn:
          type: boolean
        show_banner_preferences_btn:
          type: boolean
        show_floating_preferences_icon:
          type: boolean
        show_preferences_accept_btn:
          type: boolean
        show_preferences_accept_necessary_btn:
          type: boolean
        show_save_preferences_btn:
          type: boolean
        show_services:
          type: boolean
        swap_buttons:
          type: boolean
        target_canadian_regions:
          type: array
          items:
            type: string
          description: >-
            Province and territory codes, used when `target_type` is
            `selected_canadian_provinces`. Shares a column with
            `target_us_states`.
        target_countries:
          type: array
          items:
            type: string
          description: ISO 3166-1 alpha-2 codes
        target_type:
          type: string
          description: Who sees the banner, e.g. `worldwide`, `selected_countries`
        target_us_states:
          type: array
          items:
            type: string
        button_colors:
          type: object
          additionalProperties:
            type: string
          description: Colour overrides, keyed by button element
  responses:
    AmbiguousAccount:
      description: |
        A user API key that can reach more than one account attempted a write
        without saying which account it meant. Pass `account_id` (the account's
        API id) as a query parameter. Account keys are never ambiguous.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: 400
                message: >-
                  Specify account_id when the API key can access more than one
                  account
    AccountTokenRequired:
      description: |
        Missing or invalid API token, or a token that does not resolve to an
        account. Account-scoped endpoints accept an account token, or a user
        token whose user belongs to an account; partner tokens are rejected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: 401
                message: API key must belong to an account
    AccountAdminRequired:
      description: |
        The token resolved to a user who is not an admin of this account.
        Configuration changes are admin-only, mirroring the dashboard — a group
        admin qualifies even without a direct membership, since a group role
        supersedes one. Account tokens carry the account's own authority and
        never see this; reads are unaffected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: 403
                message: User must be an admin of this account
    NotFound:
      description: The record does not exist, or does not belong to the caller
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: 404
                message: Record not found
    ValidationError:
      description: The record could not be saved
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    RateLimited:
      description: |
        Too many requests. The general limit is 300 requests per 5 minutes per
        API token; the auth endpoints are throttled more tightly per IP.
      headers:
        Retry-After:
          description: Seconds until the current rate-limit window resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: 429
                message: Too many requests. Please retry later.
  securitySchemes:
    authorization:
      type: http
      scheme: bearer
      description: API token obtained from the login endpoint or the dashboard

````