---
title: "Validate a survey document"
method: POST
path: "/api/v3/surveys/validate"
tags: ["V3 Surveys"]
---

# Validate a survey document

`POST /api/v3/surveys/validate`

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.

## Request body

- union
  - ValidateSurveyCreateRequest
    - `operation` 'create', required
    - `data` union, required — Intended create payload. Invalid documents are allowed so the endpoint can return repairable validation errors.
      - CreateSurveyRequest — Strict v3 survey creation document. This endpoint accepts survey structure only: name, metadata, languages, welcome card, blocks/elements/logic, endings, hidden fields, and variables. It rejects legacy `questions` and out-of-scope settings such as styling, targeting, segments, follow-ups, recaptcha, single-use/email verification, slug, custom scripts, analytics fields, timestamps, and `createdBy`. Translatable fields use real locale-code maps. The map must include the `defaultLanguage` key so the server can persist the internal default translation. Locale keys are normalized case-insensitively (`de_de` → `de-DE`). Non-default locale keys must be declared in `languages`; undeclared locale keys in metadata, welcome cards, blocks, or endings are rejected with `unsupported_locale`. `blocks[].id` and `variables[].id` may be omitted on create and will be generated by the server. Provide explicit cuid2 ids when other fields in the same request reference them. For normal sequential flow, omit `logicFallback`. It is only valid together with a non-empty `logic` array on the same block.
        - `workspaceId` string, cuid2, required — Workspace where the survey will be created. Requires read/write access.
        - `name` string, required
        - `type` 'link' — Optional compatibility field. Only `link` is accepted here; app/in-app survey distribution remains outside this structure-focused create endpoint.
        - `status` 'draft' | 'inProgress' | 'paused' | 'completed'
        - `metadata` SurveyMetadata — Arbitrary JSON survey context for customer- or operation-specific metadata. v3 preserves arbitrary metadata values as-is. If present, `title` and `description` are treated as translatable text maps and returned with real locale-code keys.
          - `title` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `description` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
        - `defaultLanguage` string — Default authoring locale. Translatable maps must include this locale key.
        - `languages` CreateSurveyLanguage[] — Optional survey language configuration. Languages also referenced by translatable maps are connected automatically. If omitted, languages are derived from `defaultLanguage` and map keys.
          - `code` string, required — BCP 47 locale code. `_` separators and casing are normalized.
          - `default` boolean — Optional marker for readability; only the `defaultLanguage` entry may set this to true.
          - `enabled` boolean — Whether this language is enabled for respondent-facing delivery.
        - `welcomeCard` SurveyWelcomeCard — Optional card shown before the first survey block.
          - `enabled` boolean, required
          - `headline` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `subheader` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `fileUrl` string
          - `videoUrl` string
          - `timeToFinish` boolean
          - `showResponseCount` boolean
        - `blocks` CreateSurveyBlock[], required
          - `id` string, cuid2 — Optional stable block id. Generated when omitted.
          - `name` string, required
          - `elements` SurveyElement[], required
            - union — Survey element/question inside a block. Element ids are stable public identifiers used by logic, recall strings, response data, quotas, integrations, and analysis. `type` selects the allowed shape; unsupported fields are rejected instead of ignored.
              - …
          - `logic` SurveyBlockLogic[]
            - `id` string, cuid2, required
            - `conditions` SurveyConditionGroup, required
              - …
            - `actions` SurveyLogicAction[], required
              - …
          - `logicFallback` string, cuid2 — Block or ending id used when no logic condition matches. Only valid when this same block has at least one `logic` rule; omit it for normal sequential flow.
          - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `backButtonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
        - `endings` SurveyEnding[]
          - union — Ending reached after the last block or a jump action. `type` selects the allowed shape; unsupported fields are rejected instead of ignored.
            - SurveyEndScreenEnding — Visual end screen displayed after survey completion.
              - …
            - SurveyRedirectEnding — Redirects the respondent to a URL after survey completion. External redirects require the organization's external URL permission; otherwise write endpoints return `403 Forbidden`.
              - …
        - `hiddenFields` SurveyHiddenFields — Hidden fields, sometimes called embedded data in other survey products. Field ids are stable public identifiers and may be referenced by logic, recall, quotas, integrations, and response data. Use only letters, numbers, underscores, and hyphens; avoid spaces and reserved ids.
          - `enabled` boolean, required
          - `fieldIds` string[]
        - `variables` CreateSurveyVariable[]
          - union — Survey variable accepted by `POST /api/v3/surveys`. `id` may be omitted and will be generated by the server. Provide an explicit cuid2 id when logic in the same request needs to reference this variable.
            - CreateSurveyNumberVariable
              - …
            - CreateSurveyTextVariable
              - …
      - object
  - ValidateSurveyPatchRequest
    - `operation` 'patch', required
    - `surveyId` string, cuid2, required
    - `data` union, required — Intended patch payload. Invalid documents are allowed so the endpoint can return repairable validation errors.
      - PatchSurveyRequest — Future patch payload shape. Top-level fields are partial; any provided nested object or array fully replaces that subtree. Immutable/system fields such as `id`, `workspaceId`, `type`, timestamps, `questions`, analytics, distribution, styling, targeting, and scripts are rejected.
        - `name` string
        - `status` 'draft' | 'inProgress' | 'paused' | 'completed'
        - `metadata` SurveyMetadata — Arbitrary JSON survey context for customer- or operation-specific metadata. v3 preserves arbitrary metadata values as-is. If present, `title` and `description` are treated as translatable text maps and returned with real locale-code keys.
          - `title` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `description` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
        - `defaultLanguage` string — Default authoring locale.
        - `languages` CreateSurveyLanguage[]
          - `code` string, required — BCP 47 locale code. `_` separators and casing are normalized.
          - `default` boolean — Optional marker for readability; only the `defaultLanguage` entry may set this to true.
          - `enabled` boolean — Whether this language is enabled for respondent-facing delivery.
        - `welcomeCard` SurveyWelcomeCard — Optional card shown before the first survey block.
          - `enabled` boolean, required
          - `headline` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `subheader` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `fileUrl` string
          - `videoUrl` string
          - `timeToFinish` boolean
          - `showResponseCount` boolean
        - `blocks` SurveyBlock[]
          - `id` string, cuid2, required — Stable block id.
          - `name` string, required
          - `elements` SurveyElement[], required
            - union — Survey element/question inside a block. Element ids are stable public identifiers used by logic, recall strings, response data, quotas, integrations, and analysis. `type` selects the allowed shape; unsupported fields are rejected instead of ignored.
              - …
          - `logic` SurveyBlockLogic[]
            - `id` string, cuid2, required
            - `conditions` SurveyConditionGroup, required
              - …
            - `actions` SurveyLogicAction[], required
              - …
          - `logicFallback` string, cuid2 — Block or ending id used when no logic condition matches. Only valid when this same block has at least one `logic` rule; omit it for normal sequential flow.
          - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
          - `backButtonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey.
        - `endings` SurveyEnding[]
          - union — Ending reached after the last block or a jump action. `type` selects the allowed shape; unsupported fields are rejected instead of ignored.
            - SurveyEndScreenEnding — Visual end screen displayed after survey completion.
              - …
            - SurveyRedirectEnding — Redirects the respondent to a URL after survey completion. External redirects require the organization's external URL permission; otherwise write endpoints return `403 Forbidden`.
              - …
        - `hiddenFields` SurveyHiddenFields — Hidden fields, sometimes called embedded data in other survey products. Field ids are stable public identifiers and may be referenced by logic, recall, quotas, integrations, and response data. Use only letters, numbers, underscores, and hyphens; avoid spaces and reserved ids.
          - `enabled` boolean, required
          - `fieldIds` string[]
        - `variables` SurveyVariable[]
          - union — Survey variable. Variable ids are stable references used by logic and calculation actions. Variable names are human-readable labels and must be unique within the survey.
            - SurveyNumberVariable — Number variable. Used by `calculate` logic actions with numeric operators such as `add`, `subtract`, `multiply`, `divide`, or `assign`.
              - …
            - SurveyTextVariable — Text variable. Used by `calculate` logic actions with text operators such as `assign` or `concat`.
              - …
      - object

## Response `200`

Validation completed. The survey document may still be invalid.

- object
  - `data` SurveyValidationResult, required
    - `valid` boolean, required — Whether the submitted survey document is valid.
    - `operation` 'create' | 'patch', required
    - `invalid_params` InvalidParam[], required — Repairable validation errors using document-relative paths.
      - `name` string, required — Dot-path to the invalid request field.
      - `reason` string, required — Human-readable repair guidance.
      - `code` 'dangling_reference' | 'duplicate_identifier' | 'duplicate_locale' | 'forbidden_identifier' | 'immutable_identifier' | 'invalid_locale' | 'invalid_reference' | 'missing_required_field' | 'missing_translation' | 'unsupported_field' | 'unsupported_locale' — Machine-readable validation category, when available.
      - `identifier` string — Identifier involved in the validation failure, when available. For language errors, this can be the normalized language code.
      - `referenceType` 'block' | 'element' | 'ending' | 'hiddenField' | 'language' | 'variable' | 'variableName' | 'recall' — Identifier namespace involved in the validation failure.
      - `missingId` string — Referenced id that does not exist in the submitted survey document.
      - `firstUsedAt` string — Dot-path where a duplicate identifier was first used.
      - `conflictsWith` string — Dot-path to the existing identifier that conflicts with this field.
    - `languages` SurveyValidationLanguage[] — Languages that a successful write would connect or create. Present only when `valid=true`.
      - `code` string, required
      - `default` boolean, required
      - `enabled` boolean, required
      - `writeBehavior` 'connect_or_create', required — Validation is read-only; a real write would connect an existing language or create it if missing.

## Other responses

- `400` — Malformed validation envelope, invalid route/query data, or unsupported operation
- `401` — Not authenticated (no valid session or API key)
- `403` — Forbidden — no write access, or survey/workspace does not exist
- `429` — Rate limit exceeded
- `500` — Internal Server Error

## Changes

- **2026-05-28** `b514d6392200` — 1 info
  - endpoint added
- **2026-03-20** `9fa9931e1a70` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/formbricks/apis/formbricks-api-v3/changes/api/v3/surveys/validate/post.md)

---

[API](https://skmtc.dev/formbricks/apis/formbricks-api-v3.md) · [All operations](https://skmtc.dev/formbricks/apis/formbricks-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/formbricks/formbricks-api-v3/revisions/b514d6392200/schema)