V3 Creatives

Create a creative

Changed on Nov 2, 2026

Creates a feedback button or a banner. Requires read/write access to workspaceId. The creative is a draft unless status says otherwise.

Destination. A survey Destination must be in the same workspace, visible to the whole workspace (never Restricted, nor with a visibility change pending), and neither single-use nor PIN-protected; an http(s) link is the alternative. Anything else answers 422 naming destination.

Publish rules, checked whenever the resulting status isn't draft: a feedback button, and a banner with a button, need a destination; a banner without a button can't have one; the default language's label or message can't be empty; showOn: action needs at least one trigger. A breach answers 422 with one invalid_params entry per problem.

Languages. Every text map must hold defaultLanguage, and any other locale key must be declared in languages (422 unsupported_locale otherwise). A missing translation is fine: visitors see the default language.

Custom CSS (styling.theme.customCss). Adding it needs the Scale plan on Formbricks Cloud (403 custom_css_plan_required), and CSS that cannot be processed answers 422 naming styling.theme.customCss. Processing counts against the custom CSS budget shared with surveys; beyond it the request is a 429 and nothing is written.

post/api/v3/creatives

Request

Base URL
https://app.formbricks.com
URL
https://app.formbricks.com/api/v3/creatives
Auth
- API key in cookie next-auth.session-token
- or API key in header x-api-key
- or HTTP bearer

Request body

Example request

{
  "languages": [
    {
      "code": "en-US"
    }
  ],
  "distribution": {
    "showOn": "pageView",
    "triggers": [],
    "conditions": null,
    "displayPercentage": null
  },
  "schedule": {
    "startAt": "2026-11-01T02:00:00.000Z",
    "endAt": "2026-11-01T04:00:00.000Z"
  },
  "content": {
    "label": {
      "en-US": "Feedback",
      "de-DE": "Feedback geben"
    }
  },
  "styling": {
    "position": {
      "desktop": {
        "edge": "right",
        "offset": 50
      },
      "phone": null
    },
    "theme": {
      "customStyles": false,
      "backgroundColor": null,
      "textColor": null,
      "borderColor": null,
      "borderRadius": null,
      "fontWeight": null,
      "fontSize": {
        "desktop": null,
        "phone": null
      },
      "paddingX": {
        "desktop": null,
        "phone": null
      },
      "paddingY": {
        "desktop": null,
        "phone": null
      }
    }
  }
}

Response

Creative created

Example response

{
  "data": {
    "defaultLanguage": "en-US",
    "languages": [
      {
        "code": "en-US"
      }
    ],
    "distribution": {
      "showOn": "pageView",
      "triggers": [],
      "conditions": null,
      "displayPercentage": null
    },
    "schedule": {
      "startAt": "2026-11-01T02:00:00.000Z",
      "endAt": "2026-11-01T04:00:00.000Z"
    },
    "content": {
      "label": {
        "en-US": "Feedback",
        "de-DE": "Feedback geben"
      }
    },
    "styling": {
      "position": {
        "desktop": {
          "edge": "right",
          "offset": 50
        },
        "phone": null
      },
      "theme": {
        "customStyles": false,
        "backgroundColor": null,
        "textColor": null,
        "borderColor": null,
        "borderRadius": null,
        "fontWeight": null,
        "fontSize": {
          "desktop": null,
          "phone": null
        },
        "paddingX": {
          "desktop": null,
          "phone": null
        },
        "paddingY": {
          "desktop": null,
          "phone": null
        }
      }
    }
  }
}

Changes

Nov 2, 202603d5b9b896e2 Revision changes
- info
  added the new optional request property ////////
- info
  added the new optional request property ////////
- info
  added the required property ///////// to the response with the status
- info
  added the required property ///////// to the response with the status
Oct 28, 202684820a01e550 Revision changes
- warning
  added the new chart_in_use enum value to the response property for the response status
- warning
  added the new chart_in_use enum value to the response property for the response status
- warning
  added the new chart_in_use enum value to the response property for the response status
- warning
  added the new chart_in_use enum value to the response property for the response status
- warning
  added the new chart_in_use enum value to the response property for the response status
- warning
  added the new chart_in_use enum value to the response property for the response status
- warning
  added the new dashboards_plan_required enum value to the response property for the response status
- warning
  added the new dashboards_plan_required enum value to the response property for the response status
- warning
  added the new dashboards_plan_required enum value to the response property for the response status
- warning
  added the new dashboards_plan_required enum value to the response property for the response status
- warning
  added the new dashboards_plan_required enum value to the response property for the response status
- warning
  added the new dashboards_plan_required enum value to the response property for the response status
- warning
  added the new limit_exceeded enum value to the // response property for the response status
- warning
  added the new limit_exceeded enum value to the // response property for the response status
- warning
  added the new limit_exceeded enum value to the // response property for the response status
- warning
  added the new limit_exceeded enum value to the // response property for the response status
- warning
  added the new limit_exceeded enum value to the // response property for the response status
- warning
  added the new limit_exceeded enum value to the // response property for the response status

Operation history (3 revisions)