Validate a survey document

Validates a future create or patch survey payload without writing data, creating languages, or creating survey versions. Invalid survey documents return 200 with data.valid=false so agents and MCP clients can repair payloads from structured invalid_params.

Use 400 only for malformed validation envelopes, unsupported operations, invalid surveyId, or unsupported query parameters.

Custom CSS. A create or patch payload that carries customCss is also run through the custom CSS processor; the result adds the compiled customCss and warnings, or errors and valid=false. operation: customCss validates CSS alone for a live preview — with scope: workspace | survey and, optionally, an existing surveyId in workspaceId — and returns the compiled CSS and warnings. Validation never saves, versions, touches timestamps or invalidates caches, needs only read access, and grants nothing: the write itself checks permissions and the plan again. Requests that process custom CSS also count against a separate budget of 60 per minute per user or API key, shared with the workspace custom CSS endpoint, with survey creates and updates that add or edit custom CSS, and with the MCP tools; beyond it they return 429.

POST /api/v3/surveys/validate

cURL

createValidation

curl --request POST \
  --url https://app.formbricks.com/api/v3/surveys/validate \
  --header 'Content-Type: application/json' \
  --cookie next-auth.session-token= \
  --data '
{
  "operation": "create",
  "data": {
    "workspaceId": "clxx1234567890123456789012",
    "name": "Product Feedback Survey",
    "defaultLanguage": "en-US",
    "blocks": [
      {
        "id": "clbk1234567890123456789012",
        "name": "Main Block",
        "elements": [
          {
            "id": "satisfaction",
            "type": "openText",
            "headline": {
              "en-US": "What should we improve?"
            },
            "required": true
          }
        ]
      }
    ]
  }
}
'

200

invalid

{
  "data": {
    "valid": false,
    "operation": "create",
    "invalid_params": [
      {
        "name": "blocks.0.elements.0.buttonUrl",
        "reason": "Unsupported field 'buttonUrl' for element type 'openText'. Allowed fields..."
      }
    ]
  }
}

Authorizations

sessionAuthapiKeyAuthbearerAuth

next-auth.session-token · string · cookie · required

NextAuth session JWT cookie. Development: often next-auth.session-token. Production (HTTPS): often __Secure-next-auth.session-token. Send the cookie your browser receives after sign-in.

Body

application/json

Option 1

Option 2

Option 3

operation · enum<string> · required

Available options: create

data · object · required

Intended create payload. Invalid documents are allowed so the endpoint can return repairable validation errors.

Option 1

Option 2

Show child attributes

Response

200

application/json

Validation completed. The survey document may still be invalid.

data · object · required

Option 1

Option 2

Show child attributes