V3 Creatives

Update a creative

Changed on Nov 2, 2026

Changes a creative. Read/write access to its workspace; an unknown or inaccessible creativeId answers 403. Each group sent replaces the stored one as a whole (see PatchCreativeRequest); an empty body changes nothing.

Status. Publish with status: inProgress, pause with paused, close with completed, and reopen or resume with inProgress. A creative that was ever published can't go back to draft. Any status but draft must meet the publish rules of POST /api/v3/creatives, checked against the creative as it would be after the change, except for pausing or closing a published creative with a body that changes nothing else: taking it down works even when it no longer meets them (its last action was deleted, or its survey unlinked). In wind-down (the license does not include Creatives), only a body that sets nothing but status to paused or completed (with expectedUpdatedAt or without) is accepted; any other body, an empty one included, answers 403 creatives_not_entitled.

Custom CSS. Adding or editing styling.theme.customCss follows the rules of POST /api/v3/creatives; removing it, or sending it back unchanged, needs no plan and is not processed again.

An archived creative is read-only: restore it first, or the request answers 422.

Concurrent changes. The change applies to the creative as it is stored when the request runs, so a pause, close or archive made meanwhile is never undone by a request that doesn't mention it. Send expectedUpdatedAt (the updatedAt you last read) to have the change refused with 409 instead when the creative changed since your read.

Its survey. Changing or removing destination succeeds even when this creative is the last one that opens a live (inProgress) app survey with no actions of its own; that survey then shows nowhere until a creative or an action opens it again. Check before relinking.

patch/api/v3/creatives/{creativeId}

Request

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

Path parameters

creativeIdstring cuid2 required

Creative identifier.

Request body

namestring

status'draft' | 'inProgress' | 'paused' | 'completed'

The author's intent, and the only status a write sets: draft (never published), inProgress (published), paused (paused by its author) or completed (closed by its author). The same values as a survey's status.

What visitors get is displayStatus, which the server derives from this value, archivedAt, the schedule and the Destination survey. Nothing writes status on its own: a schedule ending or a survey pausing changes displayStatus only.

defaultLanguagestring

Canonical locale code accepted by v3 survey APIs, for example en-US, de-DE, or zh-Hans-CN.

autoSelectLanguageboolean nullable

Show the texts in the visitor's browser language when the site sets none with setLanguage and it matches the default or an enabled language; otherwise the default language is used. null (never chosen) and false both mean off. Omit to keep the stored value.

expectedUpdatedAtstring date-time

Optimistic-concurrency precondition: the creative's updatedAt from your last read. The change is applied only if the creative hasn't changed since; otherwise nothing is written and the request answers 409. Omit it to apply the change to the creative as it is stored when the request runs.

Example request

{
  "defaultLanguage": "en-US",
  "languages": [
    {
      "code": "en-US"
    }
  ],
  "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
      }
    }
  },
  "distribution": {
    "showOn": "pageView",
    "triggers": [],
    "conditions": null,
    "displayPercentage": null
  },
  "schedule": {
    "startAt": "2026-11-01T02:00:00.000Z",
    "endAt": "2026-11-01T04:00:00.000Z"
  }
}

Response

Creative updated

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 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 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 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
- warning
  added the new limit_exceeded enum value to the // response property for the response status

Operation history (3 revisions)