--- title: "Create a survey" method: POST path: "/api/v3/surveys" tags: ["V3 Surveys"] --- # Create a survey `POST /api/v3/surveys` Creates a block-based survey template from one strict survey document. The endpoint accepts multilingual authoring maps keyed by real locale codes and converts them to Formbricks' internal default-language representation. Non-default locale keys in translated content must be declared in `languages`; undeclared locale keys return `unsupported_locale` in `invalid_params` instead of silently mutating workspace languages. `blocks[].id` and `variables[].id` are stable public identifiers. They may be omitted on create, in which case the server generates cuid2 ids. If the same create request needs to reference a block or variable from logic, provide explicit valid ids and use those references consistently. For normal sequential surveys, omit `logic` and `logicFallback`. `logicFallback` is only valid when the same block has at least one `logic` rule; otherwise the API returns `invalid_reference`. This first write surface intentionally stays structure-focused: `type` may be omitted or set to `link` or `app`, but in-app survey creation and distribution-channel settings are not part of this operation. Unsupported fields are rejected instead of ignored. ## Request body - 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 canonical `defaultLanguage` key, such as `en-US`, so the server can persist the internal default translation. Locale keys must be canonical BCP 47 codes such as `de-DE`, `pt-PT`, or `zh-Hans-CN`. 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' | 'app' — Optional compatibility field. `link` and `app` survey types are accepted here; app/in-app survey distribution settings remain 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 — Canonical locale code accepted by v3 survey APIs, for example `en-US`, `de-DE`, or `zh-Hans-CN`. - `languages` CreateSurveyLanguage[] — Optional survey language configuration. Every non-default locale used by translatable maps must be declared here; omitted languages are not inferred from map keys. - `code` string, required — Canonical locale code accepted by v3 survey APIs, for example `en-US`, `de-DE`, or `zh-Hans-CN`. - `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. - SurveyOpenTextElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'openText', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `placeholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `longAnswer` boolean - `inputType` 'text' | 'email' | 'url' | 'number' | 'phone' - `insightsEnabled` boolean - `charLimit` SurveyCharLimit — Optional `openText` character limit configuration. - `enabled` boolean - `min` number - `max` number - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - SurveyConsentElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'consent', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `label` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - SurveyMultipleChoiceSingleElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'multipleChoiceSingle', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `choices` SurveyChoice[], required - `id` string, required — Stable choice id. - `label` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `shuffleOption` 'none' | 'all' | 'exceptLast' | 'reverseOrderOccasionally' | 'reverseOrderExceptLast' - `otherOptionPlaceholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `displayType` 'list' | 'dropdown' - SurveyMultipleChoiceMultiElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'multipleChoiceMulti', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `choices` SurveyChoice[], required - `id` string, required — Stable choice id. - `label` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `shuffleOption` 'none' | 'all' | 'exceptLast' | 'reverseOrderOccasionally' | 'reverseOrderExceptLast' - `otherOptionPlaceholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - `displayType` 'list' | 'dropdown' - SurveyNpsElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'nps', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `lowerLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `upperLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `isColorCodingEnabled` boolean - SurveyCtaElement — If `buttonExternal` is true, `buttonUrl` and `ctaButtonLabel` are required. - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'cta', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `buttonExternal` boolean - `buttonUrl` string - `ctaButtonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - SurveyRatingElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'rating', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `scale` 'number' | 'smiley' | 'star', required - `range` 3 | 4 | 5 | 6 | 7 | 10, required - `lowerLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `upperLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `isColorCodingEnabled` boolean - SurveyPictureSelectionElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'pictureSelection', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `allowMulti` boolean - `choices` SurveyPictureChoice[], required - `id` string, required — Stable picture choice id. - `imageUrl` string, required - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - SurveyDateElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'date', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `html` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `format` 'M-d-y' | 'd-M-y' | 'y-M-d', required - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - SurveyFileUploadElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'fileUpload', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `allowMultipleFiles` boolean, required - `maxSizeInMB` number - `allowedFileExtensions` string[] - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - SurveyCalElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'cal', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `calUserName` string, required - `calHost` string - SurveyMatrixElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'matrix', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `rows` SurveyChoice[], required - `id` string, required — Stable choice id. - `label` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `columns` SurveyChoice[], required - `id` string, required — Stable choice id. - `label` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `shuffleOption` 'none' | 'all' | 'exceptLast' | 'reverseOrderOccasionally' | 'reverseOrderExceptLast' - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - SurveyAddressElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'address', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `addressLine1` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `addressLine2` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `city` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `state` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `zip` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `country` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - SurveyRankingElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'ranking', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `choices` SurveyChoice[], required - `id` string, required — Stable choice id. - `label` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `otherOptionPlaceholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `shuffleOption` 'none' | 'all' | 'exceptLast' | 'reverseOrderOccasionally' | 'reverseOrderExceptLast' - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - SurveyContactInfoElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'contactInfo', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `firstName` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `lastName` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `email` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `phone` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `company` SurveyToggleInputConfig, required — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - … - SurveyCsatElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'csat', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `scale` 'number' | 'smiley' | 'star', required - `range` 5, required - `lowerLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `upperLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `isColorCodingEnabled` boolean - SurveyCesElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'ces', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `scale` 'number' | 'smiley' | 'star', required - `range` 5 | 7, required - `lowerLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `upperLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `isColorCodingEnabled` boolean - `logic` SurveyBlockLogic[] - `id` string, cuid2, required - `conditions` SurveyConditionGroup, required - `id` string, cuid2, required - `connector` 'and' | 'or', required - `conditions` union[], required - union - SurveyCondition — Single condition. Operators such as `isSubmitted`, `isSkipped`, `isClicked`, `isAccepted`, `isBooked`, `isSet`, and `isEmpty` do not use `rightOperand`; comparison operators do. - … - SurveyConditionGroup — recursive - `actions` SurveyLogicAction[], required - union — Logic action. Keep referenced ids stable: `calculate.variableId` points to a variable id, `requireAnswer.target` points to an element id, and `jumpToBlock.target` points to a block id or ending id. - SurveyCalculateAction — Updates a survey variable when the logic rule matches. - `id` string, cuid2, required - `objective` 'calculate', required - `variableId` string, cuid2, required — Variable id for `calculate`. - `operator` 'assign' | 'concat' | 'add' | 'subtract' | 'multiply' | 'divide', required - `value` union, required - … - SurveyRequireAnswerAction — Requires an element/question to be answered before continuing. - `id` string, cuid2, required - `objective` 'requireAnswer', required - `target` string, required — Target element id. - SurveyJumpToBlockAction — Jumps to another block or ending when the logic rule matches. - `id` string, cuid2, required - `objective` 'jumpToBlock', required - `target` string, cuid2, required — Target block id or ending id. - `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. - `id` string, cuid2, required — Stable ending id. `jumpToBlock.target` may point to this id. - `type` 'endScreen', 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. - `buttonLink` string - `imageUrl` string - `videoUrl` string - 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`. - `id` string, cuid2, required — Stable ending id. `jumpToBlock.target` may point to this id. - `type` 'redirectToUrl', required - `url` string, uri, required — External redirect URL. Requires the organization's external URL permission. - `label` string — Optional internal label for redirect endings. - `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 - `id` string, cuid2 — Optional stable variable id. Generated when omitted. - `name` string, required — Unique variable name. Lowercase letters, numbers, and underscores only. - `type` 'number', required - `value` number, required — Default numeric value. - CreateSurveyTextVariable - `id` string, cuid2 — Optional stable variable id. Generated when omitted. - `name` string, required — Unique variable name. Lowercase letters, numbers, and underscores only. - `type` 'text', required - `value` string, required — Default text value. ## Response `201` Survey created successfully - object - `data` SurveyResource, required - `id` string, required - `workspaceId` string, required - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `name` string, required - `type` 'link' | 'app' | 'website' | 'web', required - `status` 'draft' | 'inProgress' | 'paused' | 'completed', required - `metadata` SurveyMetadata, required — 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, required — Emitted language code/tag for the survey default language. The internal `default` translation key is never exposed. - `languages` SurveyLanguage[], required - `code` string, required — Server-emitted survey language code/tag used as the translatable map key. - `alias` string, nullable — Optional configured alias accepted by `?lang` for compatibility and agent discovery. - `default` boolean, required — Whether this is the default authoring language. - `enabled` boolean, required — Whether this language is enabled for respondent-facing delivery. - `welcomeCard` SurveyWelcomeCard, required — 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[], required - `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. - SurveyOpenTextElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'openText', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `placeholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `longAnswer` boolean - `inputType` 'text' | 'email' | 'url' | 'number' | 'phone' - `insightsEnabled` boolean - `charLimit` SurveyCharLimit — Optional `openText` character limit configuration. - … - `validation` SurveyValidation — Optional element-level validation rules. - … - SurveyConsentElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'consent', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `label` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `validation` SurveyValidation — Optional element-level validation rules. - … - SurveyMultipleChoiceSingleElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'multipleChoiceSingle', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `choices` SurveyChoice[], required - … - `shuffleOption` 'none' | 'all' | 'exceptLast' | 'reverseOrderOccasionally' | 'reverseOrderExceptLast' - `otherOptionPlaceholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `displayType` 'list' | 'dropdown' - SurveyMultipleChoiceMultiElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'multipleChoiceMulti', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `choices` SurveyChoice[], required - … - `shuffleOption` 'none' | 'all' | 'exceptLast' | 'reverseOrderOccasionally' | 'reverseOrderExceptLast' - `otherOptionPlaceholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `validation` SurveyValidation — Optional element-level validation rules. - … - `displayType` 'list' | 'dropdown' - SurveyNpsElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'nps', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `lowerLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `upperLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `isColorCodingEnabled` boolean - SurveyCtaElement — If `buttonExternal` is true, `buttonUrl` and `ctaButtonLabel` are required. - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'cta', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `buttonExternal` boolean - `buttonUrl` string - `ctaButtonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - SurveyRatingElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'rating', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `scale` 'number' | 'smiley' | 'star', required - `range` 3 | 4 | 5 | 6 | 7 | 10, required - `lowerLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `upperLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `isColorCodingEnabled` boolean - SurveyPictureSelectionElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'pictureSelection', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `allowMulti` boolean - `choices` SurveyPictureChoice[], required - … - `validation` SurveyValidation — Optional element-level validation rules. - … - SurveyDateElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'date', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `html` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `format` 'M-d-y' | 'd-M-y' | 'y-M-d', required - `validation` SurveyValidation — Optional element-level validation rules. - … - SurveyFileUploadElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'fileUpload', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `allowMultipleFiles` boolean, required - `maxSizeInMB` number - `allowedFileExtensions` string[] - `validation` SurveyValidation — Optional element-level validation rules. - … - SurveyCalElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'cal', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `calUserName` string, required - `calHost` string - SurveyMatrixElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'matrix', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `rows` SurveyChoice[], required - … - `columns` SurveyChoice[], required - … - `shuffleOption` 'none' | 'all' | 'exceptLast' | 'reverseOrderOccasionally' | 'reverseOrderExceptLast' - `validation` SurveyValidation — Optional element-level validation rules. - … - SurveyAddressElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'address', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `addressLine1` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `addressLine2` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `city` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `state` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `zip` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `country` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `validation` SurveyValidation — Optional element-level validation rules. - … - SurveyRankingElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'ranking', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `choices` SurveyChoice[], required - … - `otherOptionPlaceholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `shuffleOption` 'none' | 'all' | 'exceptLast' | 'reverseOrderOccasionally' | 'reverseOrderExceptLast' - `validation` SurveyValidation — Optional element-level validation rules. - … - SurveyContactInfoElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'contactInfo', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `firstName` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `lastName` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `email` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `phone` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `company` SurveyToggleInputConfig, required — Field config for address and contact info elements. - … - `validation` SurveyValidation — Optional element-level validation rules. - … - SurveyCsatElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'csat', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `scale` 'number' | 'smiley' | 'star', required - `range` 5, required - `lowerLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `upperLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `isColorCodingEnabled` boolean - SurveyCesElement - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'ces', required - `headline` TranslatableText, required — 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. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `scale` 'number' | 'smiley' | 'star', required - `range` 5 | 7, required - `lowerLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `upperLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `isColorCodingEnabled` boolean - `logic` SurveyBlockLogic[] - `id` string, cuid2, required - `conditions` SurveyConditionGroup, required - `id` string, cuid2, required - `connector` 'and' | 'or', required - `conditions` union[], required - union - … - `actions` SurveyLogicAction[], required - union — Logic action. Keep referenced ids stable: `calculate.variableId` points to a variable id, `requireAnswer.target` points to an element id, and `jumpToBlock.target` points to a block id or ending id. - SurveyCalculateAction — Updates a survey variable when the logic rule matches. - … - SurveyRequireAnswerAction — Requires an element/question to be answered before continuing. - … - SurveyJumpToBlockAction — Jumps to another block or ending when the logic rule matches. - … - `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[], required - 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. - `id` string, cuid2, required — Stable ending id. `jumpToBlock.target` may point to this id. - `type` 'endScreen', 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. - `buttonLink` string - `imageUrl` string - `videoUrl` string - 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`. - `id` string, cuid2, required — Stable ending id. `jumpToBlock.target` may point to this id. - `type` 'redirectToUrl', required - `url` string, uri, required — External redirect URL. Requires the organization's external URL permission. - `label` string — Optional internal label for redirect endings. - `hiddenFields` SurveyHiddenFields, required — 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[], required - 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`. - `id` string, cuid2, required — Stable variable id referenced from logic. - `name` string, required — Unique variable name. Lowercase letters, numbers, and underscores only. - `type` 'number', required - `value` number, required — Default numeric value. - SurveyTextVariable — Text variable. Used by `calculate` logic actions with text operators such as `assign` or `concat`. - `id` string, cuid2, required — Stable variable id referenced from logic. - `name` string, required — Unique variable name. Lowercase letters, numbers, and underscores only. - `type` 'text', required - `value` string, required — Default text value. ## Other responses - `400` — Bad Request — invalid JSON, unsupported fields, malformed multilingual maps, duplicate stable ids, or dangling logic/reference ids. - `401` — Not authenticated (no valid session or API key) - `403` — Forbidden — no write access, missing external URL permission, or workspace does not exist (404 not used; avoids existence leak) - `429` — Rate limit exceeded - `500` — Internal Server Error ## Changes - **2026-06-19** `1e4aab51b414` — 2 breaking, 1 warning, 4 info - added `subschema #2, subschema #3` to the `blocks/items/elements/items/oneOf[#/components/schemas/SurveyCtaElement]/` request property `allOf` list - the `endings/items/oneOf[#/components/schemas/SurveyRedirectEnding]/url` request property type/format changed from `string`/`` to `string`/`uri` - removed `subschema #2` from the `blocks/items/elements/items/oneOf[#/components/schemas/SurveyCtaElement]/` request property `allOf` list - added `subschema #2, subschema #3` to the `data/blocks/items/elements/items/oneOf[#/components/schemas/SurveyCtaElement]/` response property `allOf` list for the response status `201` - …3 more - **2026-06-10** `4b05a011f15c` — 1 info - added the new `app` enum value to the request property `type` - **2026-06-05** `90798c12f7ae` — 30 warning - added the new `ai_features_not_enabled` enum value to the `code` response property for the response status `400` - added the new `ai_features_not_enabled` enum value to the `code` response property for the response status `401` - added the new `ai_features_not_enabled` enum value to the `code` response property for the response status `403` - added the new `ai_features_not_enabled` enum value to the `code` response property for the response status `429` - …26 more - …earlier changes not shown [Full history](https://skmtc.dev/formbricks/apis/formbricks-api-v3/changes/api/v3/surveys/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/1e4aab51b414/schema)