--- title: "Update a survey" method: PATCH path: "/api/v3/surveys/{surveyId}" tags: ["V3 Surveys"] --- # Update a survey `PATCH /api/v3/surveys/{surveyId}` Updates a survey through a strict top-level partial document. Omitted top-level fields are preserved. Provided top-level objects and arrays replace that whole subtree; this endpoint does not deep-merge nested objects and does not implement JSON Patch. This write endpoint accepts the canonical multilingual authoring document only. Translatable fields must be locale-code maps, not strings. `PATCH ?lang=...` and `?version=...` are not supported in Scope 1. For MCP and AI-agent workflows, fetch the current survey first, modify only the intended top-level fields, call `/api/v3/surveys/validate` with `operation: patch` for preflight, then submit the same patch here. Missing ids in replaced arrays are treated as deletions. Variable name renames are allowed but may be destructive for downstream exports or integrations. Element id changes are rejected once the survey and element are no longer drafts. Optimistic concurrency (`ETag`, `If-Match`, or revision tokens) is future work; until then, overlapping writes are last-write-wins. ## Path parameters - `surveyId` string, cuid2, required ## Request body - PatchSurveyRequest — Patch payload shape. Top-level fields are partial; any provided nested object or array fully replaces that subtree. Omitted top-level fields are preserved. Immutable/system fields such as `id`, `workspaceId`, `type`, `defaultLanguage`, timestamps, `questions`, analytics, styling, and scripts are rejected. App surveys (stored `type: app`) additionally accept `distribution` and `targeting`; both are rejected for link surveys, and changing `targeting` filters requires the Contacts entitlement. `metadata`, `languages`, `welcomeCard`, `blocks`, `endings`, `hiddenFields`, and `variables` replace their full top-level value when provided. Missing ids in replaced arrays are deletions. Non-default locale keys in translatable maps must be declared in `languages`; undeclared locale keys are rejected with `unsupported_locale`. To remove a language, remove it from both `languages` and every translatable map that contains that locale key. Use `/api/v3/surveys/validate` with `operation: patch` before committing automated or agentic changes. - `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. - `languages` CreateSurveyLanguage[] — Replaces the survey language configuration. The default language cannot be changed through PATCH; any `default: true` entry must match the existing default language. Languages referenced by `metadata`, `welcomeCard`, `blocks`, or `endings` translatable maps must be explicitly declared here, so remove the locale key from those maps as well when intentionally removing a language. - `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` 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. - 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` 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`. - `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. - `distribution` SurveyDistribution — App-survey runtime/display settings. Only valid for `type: app`; rejected for link surveys. **Replacement semantics (destructive):** when `distribution` is provided on PATCH it fully replaces the stored object — any sub-field you omit is reset to its default, NOT preserved. In particular, omitting `triggers` removes ALL existing triggers, and omitting `displayOption` resets it to `displayOnce`. To change one setting, send the complete desired distribution. To leave distribution untouched, omit the whole `distribution` key. - `displayOption` 'displayOnce' | 'displayMultiple' | 'respondMultiple' | 'displaySome' — How often the survey may be shown to a contact. `displaySome` shows it up to `displayLimit` times (or until the contact responds, whichever comes first). - `displayPercentage` number, nullable — Independent throttle: show the survey to only this percentage of triggered contacts. Optional and valid with any `displayOption`; null/omitted means no throttle (shown to everyone). - `displayLimit` integer, nullable — Maximum number of times the survey is shown to a single contact. Required (must be >= 1) when `displayOption` is `displaySome`; otherwise optional. - `recontactDays` integer, nullable — Days to wait before showing this survey again to the same contact. Null uses the workspace default. - `autoClose` integer, nullable — Seconds of inactivity after which the survey widget auto-closes. Null disables auto-close. - `autoComplete` integer, nullable — Automatically stop collecting responses after this many completed responses. Null disables it. - `delay` integer — Seconds to wait after a trigger fires before showing the survey. - `triggers` SurveyTrigger[] — Action classes that trigger the survey. Every id must reference an existing workspace action class. On PATCH this list fully replaces the survey's triggers — omitting it (or sending `[]`) removes all existing triggers. - `actionClassId` string, cuid2, required — Id of an action class in the same workspace. - `targeting` SurveyTargeting — App-survey contact targeting. Only valid for `type: app`. `filters: []` targets everyone. Setting or changing non-empty filters requires the Contacts entitlement; otherwise create/patch returns 403. `attribute` filters reference workspace contact-attribute keys (discover them via `GET /api/v3/contact-attribute-keys`) and `segment` filters reference other segment ids — both are workspace-scoped resources you must obtain before constructing filters (an invalid key/id targets no one rather than erroring). See `SegmentFilter` for the per-`root.type` operator sets. - `filters` object[], required — Contact targeting filter tree. An empty array targets everyone. Each node joins the previous one via its `connector` (`and`/`or`; the first node's connector is null). A node's `resource` is either a single filter condition or a nested filter group (enabling parenthesized `and`/`or` logic). - `id` string, cuid2, required - `connector` 'and' | 'or' | 'null', nullable, required — Logical connector joining this node to the previous one. Null for the first node. - `resource` union, required — A single filter condition, or a nested filter group for grouped logic. - union — A single targeting condition. `root.type` selects the subject and determines the valid `qualifier.operator` set: `attribute` (a workspace contact-attribute key), `person` (a built-in person identifier such as `userId`/`email`), `segment` (membership in another segment), or `device`. Each variant is one member of this union; the matching member is chosen by `root.type`. - object — Matches on a workspace contact-attribute value. - `id` string, cuid2, required - `root` object, required - … - `qualifier` object, required - … - `value` union, required — Comparison value for a segment filter condition. A string or number for most operators; a relative-date object (`{ amount, unit }`) for `isOlderThan` / `isNewerThan`; a two-element `[from, to]` string array for `isBetween`. Ignored for `isSet` / `isNotSet` but still required. - … - object — Matches on a built-in person identifier. - `id` string, cuid2, required - `root` object, required - … - `qualifier` object, required - … - `value` union, required — Comparison value for a segment filter condition. A string or number for most operators; a relative-date object (`{ amount, unit }`) for `isOlderThan` / `isNewerThan`; a two-element `[from, to]` string array for `isBetween`. Ignored for `isSet` / `isNotSet` but still required. - … - object — Matches on membership in another segment. - `id` string, cuid2, required - `root` object, required - … - `qualifier` object, required - … - `value` union, required — Comparison value for a segment filter condition. A string or number for most operators; a relative-date object (`{ amount, unit }`) for `isOlderThan` / `isNewerThan`; a two-element `[from, to]` string array for `isBetween`. Ignored for `isSet` / `isNotSet` but still required. - … - object — Matches on the contact's device type. - `id` string, cuid2, required - `root` object, required - … - `qualifier` object, required - … - `value` union, required — Comparison value for a segment filter condition. A string or number for most operators; a relative-date object (`{ amount, unit }`) for `isOlderThan` / `isNewerThan`; a two-element `[from, to]` string array for `isBetween`. Ignored for `isSet` / `isNotSet` but still required. - … - SegmentFilters — recursive ## Response `200` Survey updated successfully - object - `data` SurveyResource, required - `id` string, required - `workspaceId` string, required - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `archivedAt` string, date-time, nullable, required — Soft-delete/archive marker (ISO 8601); `null` when the survey is active. - `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. - `distribution` SurveyDistribution — App-survey runtime/display settings. Only valid for `type: app`; rejected for link surveys. **Replacement semantics (destructive):** when `distribution` is provided on PATCH it fully replaces the stored object — any sub-field you omit is reset to its default, NOT preserved. In particular, omitting `triggers` removes ALL existing triggers, and omitting `displayOption` resets it to `displayOnce`. To change one setting, send the complete desired distribution. To leave distribution untouched, omit the whole `distribution` key. - `displayOption` 'displayOnce' | 'displayMultiple' | 'respondMultiple' | 'displaySome' — How often the survey may be shown to a contact. `displaySome` shows it up to `displayLimit` times (or until the contact responds, whichever comes first). - `displayPercentage` number, nullable — Independent throttle: show the survey to only this percentage of triggered contacts. Optional and valid with any `displayOption`; null/omitted means no throttle (shown to everyone). - `displayLimit` integer, nullable — Maximum number of times the survey is shown to a single contact. Required (must be >= 1) when `displayOption` is `displaySome`; otherwise optional. - `recontactDays` integer, nullable — Days to wait before showing this survey again to the same contact. Null uses the workspace default. - `autoClose` integer, nullable — Seconds of inactivity after which the survey widget auto-closes. Null disables auto-close. - `autoComplete` integer, nullable — Automatically stop collecting responses after this many completed responses. Null disables it. - `delay` integer — Seconds to wait after a trigger fires before showing the survey. - `triggers` SurveyTrigger[] — Action classes that trigger the survey. Every id must reference an existing workspace action class. On PATCH this list fully replaces the survey's triggers — omitting it (or sending `[]`) removes all existing triggers. - `actionClassId` string, cuid2, required — Id of an action class in the same workspace. - `targeting` SurveyTargeting — App-survey contact targeting. Only valid for `type: app`. `filters: []` targets everyone. Setting or changing non-empty filters requires the Contacts entitlement; otherwise create/patch returns 403. `attribute` filters reference workspace contact-attribute keys (discover them via `GET /api/v3/contact-attribute-keys`) and `segment` filters reference other segment ids — both are workspace-scoped resources you must obtain before constructing filters (an invalid key/id targets no one rather than erroring). See `SegmentFilter` for the per-`root.type` operator sets. - `filters` object[], required — Contact targeting filter tree. An empty array targets everyone. Each node joins the previous one via its `connector` (`and`/`or`; the first node's connector is null). A node's `resource` is either a single filter condition or a nested filter group (enabling parenthesized `and`/`or` logic). - `id` string, cuid2, required - `connector` 'and' | 'or' | 'null', nullable, required — Logical connector joining this node to the previous one. Null for the first node. - `resource` union, required — A single filter condition, or a nested filter group for grouped logic. - union — A single targeting condition. `root.type` selects the subject and determines the valid `qualifier.operator` set: `attribute` (a workspace contact-attribute key), `person` (a built-in person identifier such as `userId`/`email`), `segment` (membership in another segment), or `device`. Each variant is one member of this union; the matching member is chosen by `root.type`. - object — Matches on a workspace contact-attribute value. - … - object — Matches on a built-in person identifier. - … - object — Matches on membership in another segment. - … - object — Matches on the contact's device type. - … - SegmentFilters — recursive ## Other responses - `400` — Bad Request — the patch failed schema validation, i.e. any rule checkable from the request body alone, without consulting stored state. Covers: malformed JSON; an unsupported query parameter; unknown, unsupported, or immutable fields (`type` cannot be changed after creation, and `distribution`/`targeting` are `app`-only — sending them when patching a `link` survey is rejected); wrong types or out-of-range values; bad enum values; malformed multilingual maps; and intra-document field-combination rules — notably `displayLimit` is required (must be >= 1) when `displayOption` is `displaySome`. Cross-reference failures that need stored state to detect return **422** instead. Every offending field is itemized in `invalid_params`. Unknown, forbidden, immutable, or wrongly-combined fields carry `code: unsupported_field` (e.g. `type`, or `distribution`/`targeting` on a link survey); omissions carry `code: missing_required_field`. Bare type, range, enum, and malformed-locale-map violations report the field `name` with a human-readable `reason` and no machine `code`. - `401` — Not authenticated (no valid session or API key). - `403` — Forbidden — no write access, missing external URL permission, missing Contacts entitlement for app-survey targeting, or survey does not exist (404 not used; avoids existence leak) - `422` — Unprocessable Content — the request cannot be processed against stored state. Two cases: 1. The target survey is archived (soft-deleted) and therefore read-only; restore it before editing. The `invalid_params` entry reports `name: archivedAt` with the reason `This survey is archived. Restore it before editing.` 2. The patched document passed schema validation but failed a cross-reference check that requires stored state to detect: an undeclared locale key used in content, a duplicate stable id, an immutable element-id change on a published survey, a dangling logic/jump reference, an invalid media URL, a `distribution.triggers[].actionClassId` referencing an action class that does not exist in the workspace (discover valid ids via `GET /api/v3/action-classes`), or a `targeting.filters` entry that cannot resolve in the workspace — an unknown contact-attribute key or segment, an unsupported person identifier, or an unknown device value. The `invalid_params` array pinpoints each issue (e.g. `code: invalid_reference` with the offending `identifier`). - `429` — Rate limit exceeded. - `500` — Internal Server Error. --- [API](https://skmtc.net/formbricks/apis/formbricks-api-v3.md) · [All operations](https://skmtc.net/formbricks/apis/formbricks-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/formbricks/formbricks-api-v3/versions/552e527a8e9f/schema)