---
title: Update survey
description: "Updates metadata, targeting, and content variants. For published surveys, changes apply to a draft until publish in the UI. latest version is required and mu…"
product: general
lang: en
last_updated: 2026-10-27
token_estimate: 19865
---
# Update survey

## Update survey

**PATCH** `/v1/projects/{project_id}/surveys/{survey_id}`

Full URL: `https://developer-api.amplitude.com/v1/projects/{project_id}/surveys/{survey_id}`

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

**Servers:**
- Production (US): `https://developer-api.amplitude.com/v1/projects/{project_id}/surveys/{survey_id}`
- Production (EU): `https://developer-api.eu.amplitude.com/v1/projects/{project_id}/surveys/{survey_id}`

Update survey

Updates metadata, targeting, and content variants. For published surveys,
changes apply to a draft until publish in the UI. `latest_version` is
required and must match the current draft, otherwise the update returns
`409`. The check runs before the write rather than atomically with it, so it
reduces but does not fully prevent lost updates from concurrent writers.
Publish, schedule, and test instrumentation are not
available via API in v1. Status fields on the response are derived read-only.
When `variants` is sent, it must list every existing variant by `id` with
its unchanged `variant` key; steps within a variant can be added, edited,
reordered, or removed. `tags` is not writable in v1 and returns `400`.

To add, change, or clear translations, send
`variants: [{"id": "<variant id>", "translations": {...}}]`. Entries
that carry only `id` and `translations` may name a subset of the variants
and need no `variant` key. `translations` maps locale to translation key to
text. Take the keys and their default-locale text from
`translation_status.sources` on a `GET` with
`include_translations=true&include_unpublished_changes=true`. Translations
merge into what is stored: keys you leave out keep their text, `null`
clears a key, and `null` for a locale clears every key in it. Only steps
and blocks that already exist can be translated, so add new content
first, then translate it in a later request. The default locale is edited
through the survey content, not `translations`. When the request sends
translations, the response includes `localization`, `translations`, and
`translation_status`. Translations return `400` when localization is
disabled in the project settings or the locale isn't one of the
project's locales.

## Authorizations

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| Authorization | string | Yes | — | http |

## Path parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| project_id (path) | string | Yes | 12345 | Amplitude project identifier, backed by the canonical app ID. Constraints: pattern: ^[0-9]+$ |
| survey_id (path) | string | Yes | — | Survey nudge identifier. Constraints: pattern: ^[0-9]+$ |

## Header parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| Idempotency-Key (header) | string | Yes | — | Required on write operations. Keys aren't stored yet, so retrying a write with the same key performs it again; a retried create makes another resource. Check whether the first attempt succeeded before you retry. Constraints: min length: 8, max length: 255 |

## Body (application/json)

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| title | string | No | — | Constraints: min length: 1, max length: 255 |
| description | string | No | — | Constraints: nullable |
| platform | string | No | — | Target platform. Guides and surveys without an explicit platform are returned as `web`. Allowed values: web, ios, android, react-native, desktop, flutter |
| priority | integer | No | — | Constraints: min: 1, max: 4 |
| page_target_segments | object[] | No | — | Pages where the survey is eligible. Empty means every page. Each item uses camelCase keys. |
| page_target_segments.url | string | Yes | — | Page URL or pattern for the URL match types. |
| page_target_segments.matchType | string | Yes | — | Allowed values: simple, exact, pattern, contains, startsWith, endsWith, regex, domSelector |
| page_target_segments.isExclude | boolean | Yes | — | When true, matching pages are excluded. |
| page_target_segments.operator | string | No | — | How this rule combines with the next one. Allowed values: and, or |
| page_target_segments.value | string | No | — | CSS selector of an element that must be on the page. Required for `domSelector`, which is web only. |
| temporarily_hide_page_target_segments | object[] | No | — | Page rules that are saved but not currently applied. |
| temporarily_hide_page_target_segments.url | string | Yes | — | Page URL or pattern for the URL match types. |
| temporarily_hide_page_target_segments.matchType | string | Yes | — | Allowed values: simple, exact, pattern, contains, startsWith, endsWith, regex, domSelector |
| temporarily_hide_page_target_segments.isExclude | boolean | Yes | — | When true, matching pages are excluded. |
| temporarily_hide_page_target_segments.operator | string | No | — | How this rule combines with the next one. Allowed values: and, or |
| temporarily_hide_page_target_segments.value | string | No | — | CSS selector of an element that must be on the page. Required for `domSelector`, which is web only. |
| hide_if_page_targeting_not_met | boolean | No | — | — |
| trigger_config | oneOf | No | — | When the guide or survey appears. One trigger, or an array of triggers where any match fires it. Nested keys keep their stored names (`selector`, `event`, `event_count`, `delay`, `filters`). Don't send `null`: the dashboard can't open a guide or survey without a trigger. Send `{"type": "immediately"}` to show right away. Constraints: oneOf (object), oneOf[] |
| trigger_config.type | string | No | — | Allowed values: immediately, none, smart_delay, rage_click, user_confusion, exit_intent, element_appeared, element_clicked |
| trigger_config.data | object | No | — | — |
| trigger_config.data.delay | number | No | — | Milliseconds to wait after the trigger fires. Omit it rather than sending null. Constraints: min: 0 |
| trigger_config.data.sessionPropertyFilters | object[][] | No | — | Session property conditions. The inner arrays are AND groups, and the outer array ORs them. |
| trigger_config.data.selector | string | No | — | CSS selector of the element. |
| trigger_config.data.event | string | No | — | Analytics event type that fires the trigger. |
| trigger_config.data.event_count | integer | No | — | Times the event must occur. Omitted means once. Constraints: min: 1 |
| trigger_config.data.filters | object[] | No | — | Event property conditions. Every condition must match. |
| trigger_config.data.filters.subprop_key | string | Yes | — | Property name. Constraints: min length: 1 |
| trigger_config.data.filters.subprop_op | string | Yes | — | Comparison operator, for example `is`, `is not`, or `contains`. |
| trigger_config.data.filters.subprop_value | string[] | Yes | — | Values to compare against. |
| trigger_config.data.filters.subprop_type | string | No | — | Property type, for example `event` or `user`. Constraints: nullable |
| trigger_config.data.filters.group_type | string | No | — | Constraints: nullable |
| trigger_config.data.unit | string | No | — | Allowed values: second, minute |
| trigger_config.data.value | number | No | — | How long to wait on the page before showing. |
| lifecycle | object | No | — | How often the guide or survey may show again. `periodCount` is camelCase; the other keys are snake_case. Send the whole object, not `null`. |
| lifecycle.stop_showing_if_completed | boolean | Yes | — | — |
| lifecycle.stop_showing_if_dismissed | boolean | Yes | — | — |
| lifecycle.survey_response_cap | object | No | — | — |
| lifecycle.survey_response_cap.enabled | boolean | No | — | — |
| lifecycle.survey_response_cap.value | integer | No | — | Stop after this many survey responses. Required when `enabled` is true. Constraints: min: 1 |
| lifecycle.cooldown_limits | object[] | Yes | — | — |
| lifecycle.cooldown_limits.max | integer | Yes | — | Maximum impressions in the period. Constraints: min: 1 |
| lifecycle.cooldown_limits.periodCount | integer | No | — | How many `period`s the limit covers. Omitted means 1. Constraints: min: 1 |
| lifecycle.cooldown_limits.period | string | Yes | — | Allowed values: day, week, month, year, session |
| lifecycle.even_distribution | object | No | — | — |
| lifecycle.even_distribution.enabled | boolean | Yes | — | — |
| lifecycle.even_distribution.recurrence_period_days | integer | Yes | — | Days over which impressions are spread evenly. Always required when `even_distribution` is sent. Constraints: min: 1 |
| dismissible | boolean | No | — | — |
| snoozable | boolean | No | — | — |
| snoozable_on_all_steps | boolean | No | — | — |
| snooze_duration | object | No | — | How long a snooze lasts. |
| snooze_duration.interval | string | Yes | — | Allowed values: hour, day, week |
| snooze_duration.value | number | Yes | — | Number of intervals. |
| snooze_label | string | No | — | Snooze button label. Constraints: max length: 255 |
| template_source | string | No | — | Constraints: max length: 255 |
| show_step_counter | boolean | No | — | — |
| step_counter_format | string | No | — | `numeric` shows "1/3"; `verbose` shows "Step 1 of 3". Allowed values: numeric, verbose |
| tags | string[] | No | — | — |
| variants | object[] | No | — | — |
| variants.id | string | No | — | — |
| variants.variant | string | No | — | Variant key within the nudge: lowercase letters, digits, `-` and `_`. Keys must be unique. `off` is reserved, and `control` can't be given to a new variant. Constraints: pattern: ^[a-z0-9_-]+$ |
| variants.display_title | string | No | — | Variant title. Omit it to leave it unchanged; `null` is rejected. |
| variants.display_description | string | No | — | Constraints: nullable |
| variants.snooze_label | string | No | — | Snooze button label for this variant. Omit it to leave it unchanged; `null` is rejected. Constraints: max length: 255 |
| variants.done_label | string | No | — | Label of the last step's button. Omit it to leave it unchanged; `null` is rejected. Constraints: max length: 255 |
| variants.steps | object[] | No | — | — |
| variants.steps.id | string | No | — | — |
| variants.steps.title | string | No | — | Step title. Omit it to leave it unchanged; `null` is rejected. Constraints: max length: 255 |
| variants.steps.form_factor | oneOf | No | — | Step layout. `type` selects it. Every form factor also accepts `zIndexOverride` (number or null) and `textAnimation` (`typewriter`). Modal, popover, pin, tooltip, and card accept the step layout keys `layout`, `mediaPosition`, `contentAlignment`, `titleAlignment`, and `footerLayout`; banner and checklist accept a narrower set. Tooltips and cards can't be snoozed. Constraints: object |
| variants.steps.form_factor.type | string | Yes | — | — |
| variants.steps.form_factor.position | string | No | — | Where a modal or popover sits in the viewport. Allowed values: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right, left-center, right-center, center, top, bottom, auto, left, right, prepend, append, replace, before, after |
| variants.steps.form_factor.canClickOutsideToClose | boolean | No | — | — |
| variants.steps.form_factor.fullWidthModal | boolean | No | — | — |
| variants.steps.form_factor.layout | string | No | — | Arrangement of media and text in the step. Allowed values: classic, vertical, showcase, horizontal |
| variants.steps.form_factor.mediaPosition | string | No | — | Media side for the `horizontal` layout. Allowed values: left, right |
| variants.steps.form_factor.contentAlignment | string | No | — | Allowed values: start, center, end |
| variants.steps.form_factor.titleAlignment | string | No | — | Allowed values: start, center, end |
| variants.steps.form_factor.footerLayout | string | No | — | Arrangement of the step's buttons. Allowed values: classic, split, centered, stacked |
| variants.steps.form_factor.placement | string | No | — | Allowed values: default, overlay |
| variants.steps.form_factor.sticky | boolean | No | — | Keep the banner on screen while the page scrolls. |
| variants.steps.form_factor.anchor | string | No | — | CSS selector the pin attaches to. |
| variants.steps.form_factor.anchorSelector | object | No | — | Richer element match used alongside `anchor`. |
| variants.steps.form_factor.anchorSelector.selector | string | Yes | — | — |
| variants.steps.form_factor.anchorSelector.text | string | Yes | — | Visible text of the element. |
| variants.steps.form_factor.anchorSelector.tag | string | Yes | — | HTML tag name. |
| variants.steps.form_factor.anchorSelector.attributes | object | Yes | — | — |
| variants.steps.form_factor.anchorSelector.strategy | string | No | — | Allowed values: strict, fallback, selector_only |
| variants.steps.form_factor.alignment | string | No | — | Allowed values: center, top, bottom, left, right, start, end |
| variants.steps.form_factor.offset | object | No | — | Both `x` and `y` are required. |
| variants.steps.form_factor.offset.x | string | Yes | — | CSS length, for example `0px`. |
| variants.steps.form_factor.offset.y | string | Yes | — | CSS length, for example `0px`. |
| variants.steps.form_factor.pointer | object | No | — | — |
| variants.steps.form_factor.pointer.type | string | Yes | — | Allowed values: beacon, arrow, none |
| variants.steps.form_factor.isOpenByDefault | boolean | No | — | — |
| variants.steps.form_factor.openOnHover | boolean | No | — | — |
| variants.steps.form_factor.isShowingMask | boolean | No | — | Dim the rest of the page. |
| variants.steps.form_factor.advanceTrigger | string | No | — | CSS selector whose click advances to the next step. |
| variants.steps.form_factor.disableAutoAdvanceOnClick | boolean | No | — | — |
| variants.steps.form_factor.skipIfNotFound | boolean | No | — | Skip the step when the anchor is missing. |
| variants.steps.form_factor.showOn | string | No | — | Allowed values: hover, click |
| variants.steps.form_factor.marker | oneOf | No | — | The marker users hover or click to open the tooltip. Every marker type also accepts `width` (number) and `elementIsMarker` (boolean). Constraints: object |
| variants.steps.form_factor.marker.type | string | Yes | — | — |
| variants.steps.form_factor.marker.positioning | object | Yes | — | — |
| variants.steps.form_factor.marker.positioning.position | string | Yes | — | Allowed values: left, right, inline_left, inline_right |
| variants.steps.form_factor.marker.positioning.offset | object | Yes | — | Both `x` and `y` are required. |
| variants.steps.form_factor.marker.positioning.offset.x | string | Yes | — | CSS length, for example `0px`. |
| variants.steps.form_factor.marker.positioning.offset.y | string | Yes | — | CSS length, for example `0px`. |
| variants.steps.form_factor.marker.icon | string | No | — | Allowed values: helpCircle, helpSquare, infoCircle, bookClosed, lightBulb, lightning |
| variants.steps.form_factor.marker.source | string | No | — | Image URL. |
| variants.steps.form_factor.cardWidth | object | No | — | — |
| variants.steps.form_factor.cardWidth.type | string | Yes | — | Allowed values: auto, fixed, full |
| variants.steps.form_factor.cardWidth.value | number | No | — | Pixels, used with `fixed`. |
| variants.steps.form_factor.cardHeight | object | No | — | — |
| variants.steps.form_factor.cardHeight.type | string | Yes | — | Allowed values: auto, fixed, full |
| variants.steps.form_factor.cardHeight.value | number | No | — | Pixels, used with `fixed`. |
| variants.steps.form_factor.cardMargin | object | No | — | — |
| variants.steps.form_factor.cardMargin.top | number | Yes | — | — |
| variants.steps.form_factor.cardMargin.right | number | Yes | — | — |
| variants.steps.form_factor.cardMargin.bottom | number | Yes | — | — |
| variants.steps.form_factor.cardMargin.left | number | Yes | — | — |
| variants.steps.content | oneOf[] | No | [{"uuid":"3f0c2a8e-5b1d-4c7a-9e2f-1a6b8d4c0e11","type":"markdown","meta":{"value":"Track any event in two clicks."}},{"uuid":"8d2e6f1a-7c3b-4e9d-a0f5-2b7c9e1d3a42","type":"button","meta":{"label":"Next","buttonType":"primary","action":{"type":"step_forward"}}}] | The step body: content blocks rendered top to bottom, below the step `title`. `meta` keys are camelCase. Keep a block's existing `uuid` when you edit it, because survey responses are keyed by it; a block sent without one (or with `null`) is given one on save. To change one block, send the step's whole `content` array back with that block edited. Send `[]` for an empty step, not `null`. A step can have at most one `markdown` block, one `image` or one `video` (not both), two buttons, ten survey questions, and ten `survey_hidden` fields. Survey question blocks are only allowed in surveys, and only on steps with the `classic` or `vertical` layout. A checklist item can have at most one button. A snooze button needs the variant's `snooze_label`. |
| variants.steps.content.uuid | string | No | — | Constraints: nullable |
| variants.steps.content.type | string | Yes | — | `survey_text` is a multi-line answer; `survey_text_short` is a single line. Allowed values: survey_text, survey_text_short |
| variants.steps.content.meta | object | Yes | — | — |
| variants.steps.content.meta.value | string | No | — | Markdown text. Inline HTML is allowed and is sanitized on save. |
| variants.steps.content.meta.alignment | string | No | — | Allowed values: start, center, end |
| variants.steps.content.meta.textAnimation | string | No | — | — |
| variants.steps.content.meta.src | string | No | — | Image URL. |
| variants.steps.content.meta.filename | string | No | — | — |
| variants.steps.content.meta.size | string | No | — | — |
| variants.steps.content.meta.altText | string | No | — | — |
| variants.steps.content.meta.style | object | No | — | — |
| variants.steps.content.meta.style.scale | string | No | — | — |
| variants.steps.content.meta.style.radius | string | No | — | — |
| variants.steps.content.meta.style.fit | string | No | — | Allowed values: cover, contain |
| variants.steps.content.meta.style.height | string | No | — | — |
| variants.steps.content.meta.action | object | No | {"type":"link","value":"https://example.com/pricing","operation":"blank"} | Optional link opened when the image is clicked. No other action type is allowed. |
| variants.steps.content.meta.action.type | string | Yes | — | Common actions: - `step_forward`, `step_back`: go to the next or previous step. - `complete`: finish the guide or survey. - `dismiss`: close it. - `snooze`: hide it for a while, with optional `interval` (`hour`, `day`, `week`) and `value`. - `go_to_step`: jump to a step. `value` is the 0-based position of the step in the variant's `steps`, not its id. - `link`: open the URL in `value`; `operation` is `self` (same tab), `blank` (new tab) or `router`. - `nudge`: start another guide or survey. `value` is its numeric id, and `productType` is `guide` or `survey`. - `no_action`: no action of its own. The button still advances: to the next step, or on the last step it finishes the guide or survey. The dashboard's survey templates use it for the submit button. It does not keep the user on the step; `stay_on_step` does. Buttons built in the dashboard can also use `stay_on_step`, `click` (`value` is a CSS selector), `callback`, `app_review`, `open_resource_center`, `open_ai_assistant`, `open_chat`, `document`, `video`, and `use_conditional_logic`. Send those back unchanged. |
| variants.steps.content.meta.action.value | string | No | — | URL to open. |
| variants.steps.content.meta.action.operation | string | No | — | Allowed values: self, blank, router |
| variants.steps.content.meta.type | string | No | — | `nps` is a 0–10 scale and takes `options: 10`. Allowed values: stars, numbers, emojis, nps |
| variants.steps.content.meta.label | string | No | — | — |
| variants.steps.content.meta.buttonType | string | No | — | Allowed values: primary, secondary, snooze |
| variants.steps.content.meta.grow | boolean | No | — | Stretch the button to fill the footer row. |
| variants.steps.content.meta.width | string | No | — | CSS width, for example `100%`. |
| variants.steps.content.meta.actions | object | No | — | Optional action sequence the dashboard writes for buttons with side effects: `{type: "action_sequence", navigation: <action>, effects: [<action>]}`. When present, the SDK runs it instead of `action`, so update both or neither. |
| variants.steps.content.meta.prompt | string | No | — | Placeholder shown in the empty answer field. Required; send `""` for none. |
| variants.steps.content.meta.ariaLabel | string | No | — | — |
| variants.steps.content.meta.prefill | object | No | — | `survey_text_short` only. |
| variants.steps.content.meta.prefill.enabled | boolean | Yes | — | — |
| variants.steps.content.meta.prefill.userProperty | string | Yes | — | User property whose value fills the answer. |
| variants.steps.content.meta.validation | object | No | — | — |
| variants.steps.content.meta.validation.required | object | No | — | — |
| variants.steps.content.meta.validation.required.value | boolean | Yes | — | — |
| variants.steps.content.meta.validation.required.message | string | No | — | Error shown when a required question is left empty. Required when `value` is `true`. Constraints: nullable |
| variants.steps.content.meta.options | array or integer | No | — | Number of choices on the scale. Allowed values depend on `type`: `stars` 3 or 5, `numbers` 3, 5, 7 or 10, `emojis` 2, 3 or 5, and `nps` 10. |
| variants.steps.content.meta.listType | string | No | — | Allowed values: single, multiple |
| variants.steps.content.meta.displayType | string | No | — | Allowed values: list, dropdown, grid |
| variants.steps.content.meta.isOrderRandom | boolean | No | — | — |
| variants.steps.content.meta.otherOption | object | No | — | — |
| variants.steps.content.meta.otherOption.enabled | boolean | Yes | — | — |
| variants.steps.content.meta.otherOption.label | string | Yes | — | — |
| variants.steps.content.meta.otherOption.placeholderLabel | string | Yes | — | — |
| variants.steps.content.meta.emojis | string[] | No | — | Exactly one emoji per option. Required when `type` is `emojis`. |
| variants.steps.content.meta.lowerLabel | string | No | — | — |
| variants.steps.content.meta.upperLabel | string | No | — | — |
| variants.steps.content.meta.source | oneOf | No | — | Constraints: object |
| variants.steps.content.meta.source.type | string | Yes | — | — |
| variants.steps.content.meta.source.value | string | No | — | The value to record. |
| variants.steps.content.meta.source.property | string | No | — | Property of the event that triggered the survey. |
| variants.steps.content_v2 | oneOf | No | — | Block-builder layout: a tree of `layout` containers whose `children` are containers or content blocks, including the step's `title` block. Returned only on steps built in the block builder; when present, the dashboard and SDK render this tree, not `title` and `content`. On update, only accepted on resources that already have a step with a tree; a flat-only guide or survey can't be converted through the API. On create, any step may take one, so a resource read with `content_v2` can be copied. Block `uuid`s must be unique within the step. Keep a block's existing `uuid` when you edit it, because survey responses are keyed by it; a block sent without one is given one on save. The saved tree is normalized to the shape the block builder saves, and the step title is taken from its `title` block. On a step with a tree, send `title` and `content` only together with `content_v2`. Not supported on banner or checklist steps or on mobile platforms. `null` switches the step back to `content`. Constraints: object, null |
| variants.steps.content_v2.type | string | No | — | — |
| variants.steps.content_v2.children | oneOf[] | No | — | — |
| variants.steps.content_v2.children.uuid | string | No | — | Constraints: nullable |
| variants.steps.content_v2.children.type | string | No | — | `survey_text` is a multi-line answer; `survey_text_short` is a single line. Allowed values: survey_text, survey_text_short |
| variants.steps.content_v2.children.meta | object | No | — | — |
| variants.steps.content_v2.children.meta.value | string | No | — | Markdown text. Inline HTML is allowed and is sanitized on save. |
| variants.steps.content_v2.children.meta.alignment | string | No | — | Allowed values: start, center, end |
| variants.steps.content_v2.children.meta.textAnimation | string | No | — | — |
| variants.steps.content_v2.children.meta.src | string | No | — | Image URL. |
| variants.steps.content_v2.children.meta.filename | string | No | — | — |
| variants.steps.content_v2.children.meta.size | string | No | — | — |
| variants.steps.content_v2.children.meta.altText | string | No | — | — |
| variants.steps.content_v2.children.meta.style | object | No | — | — |
| variants.steps.content_v2.children.meta.style.scale | string | No | — | — |
| variants.steps.content_v2.children.meta.style.radius | string | No | — | — |
| variants.steps.content_v2.children.meta.style.fit | string | No | — | Allowed values: cover, contain |
| variants.steps.content_v2.children.meta.style.height | string | No | — | — |
| variants.steps.content_v2.children.meta.action | object | No | {"type":"link","value":"https://example.com/pricing","operation":"blank"} | Optional link opened when the image is clicked. No other action type is allowed. |
| variants.steps.content_v2.children.meta.action.type | string | Yes | — | Common actions: - `step_forward`, `step_back`: go to the next or previous step. - `complete`: finish the guide or survey. - `dismiss`: close it. - `snooze`: hide it for a while, with optional `interval` (`hour`, `day`, `week`) and `value`. - `go_to_step`: jump to a step. `value` is the 0-based position of the step in the variant's `steps`, not its id. - `link`: open the URL in `value`; `operation` is `self` (same tab), `blank` (new tab) or `router`. - `nudge`: start another guide or survey. `value` is its numeric id, and `productType` is `guide` or `survey`. - `no_action`: no action of its own. The button still advances: to the next step, or on the last step it finishes the guide or survey. The dashboard's survey templates use it for the submit button. It does not keep the user on the step; `stay_on_step` does. Buttons built in the dashboard can also use `stay_on_step`, `click` (`value` is a CSS selector), `callback`, `app_review`, `open_resource_center`, `open_ai_assistant`, `open_chat`, `document`, `video`, and `use_conditional_logic`. Send those back unchanged. |
| variants.steps.content_v2.children.meta.action.value | string | No | — | URL to open. |
| variants.steps.content_v2.children.meta.action.operation | string | No | — | Allowed values: self, blank, router |
| variants.steps.content_v2.children.meta.type | string | No | — | `nps` is a 0–10 scale and takes `options: 10`. Allowed values: stars, numbers, emojis, nps |
| variants.steps.content_v2.children.meta.label | string | No | — | — |
| variants.steps.content_v2.children.meta.buttonType | string | No | — | Allowed values: primary, secondary, snooze |
| variants.steps.content_v2.children.meta.grow | boolean | No | — | Stretch the button to fill the footer row. |
| variants.steps.content_v2.children.meta.width | string | No | — | CSS width, for example `100%`. |
| variants.steps.content_v2.children.meta.actions | object | No | — | Optional action sequence the dashboard writes for buttons with side effects: `{type: "action_sequence", navigation: <action>, effects: [<action>]}`. When present, the SDK runs it instead of `action`, so update both or neither. |
| variants.steps.content_v2.children.meta.prompt | string | No | — | Placeholder shown in the empty answer field. Required; send `""` for none. |
| variants.steps.content_v2.children.meta.ariaLabel | string | No | — | — |
| variants.steps.content_v2.children.meta.prefill | object | No | — | `survey_text_short` only. |
| variants.steps.content_v2.children.meta.prefill.enabled | boolean | Yes | — | — |
| variants.steps.content_v2.children.meta.prefill.userProperty | string | Yes | — | User property whose value fills the answer. |
| variants.steps.content_v2.children.meta.validation | object | No | — | — |
| variants.steps.content_v2.children.meta.validation.required | object | No | — | — |
| variants.steps.content_v2.children.meta.validation.required.value | boolean | Yes | — | — |
| variants.steps.content_v2.children.meta.validation.required.message | string | No | — | Error shown when a required question is left empty. Required when `value` is `true`. Constraints: nullable |
| variants.steps.content_v2.children.meta.options | array or integer | No | — | Number of choices on the scale. Allowed values depend on `type`: `stars` 3 or 5, `numbers` 3, 5, 7 or 10, `emojis` 2, 3 or 5, and `nps` 10. |
| variants.steps.content_v2.children.meta.listType | string | No | — | Allowed values: single, multiple |
| variants.steps.content_v2.children.meta.displayType | string | No | — | Allowed values: list, dropdown, grid |
| variants.steps.content_v2.children.meta.isOrderRandom | boolean | No | — | — |
| variants.steps.content_v2.children.meta.otherOption | object | No | — | — |
| variants.steps.content_v2.children.meta.otherOption.enabled | boolean | Yes | — | — |
| variants.steps.content_v2.children.meta.otherOption.label | string | Yes | — | — |
| variants.steps.content_v2.children.meta.otherOption.placeholderLabel | string | Yes | — | — |
| variants.steps.content_v2.children.meta.emojis | string[] | No | — | Exactly one emoji per option. Required when `type` is `emojis`. |
| variants.steps.content_v2.children.meta.lowerLabel | string | No | — | — |
| variants.steps.content_v2.children.meta.upperLabel | string | No | — | — |
| variants.steps.content_v2.children.meta.source | oneOf | No | — | Constraints: object |
| variants.steps.content_v2.children.meta.source.type | string | Yes | — | — |
| variants.steps.content_v2.children.meta.source.value | string | No | — | The value to record. |
| variants.steps.content_v2.children.meta.source.property | string | No | — | Property of the event that triggered the survey. |
| variants.steps.content_v2.children.meta.format | string | No | — | Allowed values: numeric, verbose |
| variants.steps.content_v2.id | string | No | — | Container id, unique within the step. |
| variants.steps.content_v2.direction | string | No | — | Allowed values: row, column |
| variants.steps.content_v2.justify | string | No | — | Allowed values: start, center, end, space-between, space-around |
| variants.steps.content_v2.align | string | No | — | Allowed values: start, center, end |
| variants.steps.content_v2.gap | string | No | — | CSS length, for example `8px`. |
| variants.steps.content_v2.padding | string | No | — | — |
| variants.steps.content_v2.margin | string | No | — | — |
| variants.steps.content_v2.pinned | boolean | No | — | — |
| variants.steps.content_v2.wrap | boolean | No | — | — |
| variants.steps.content_v2.overflow | string | No | — | Allowed values: auto, hidden |
| variants.steps.content_v2.minHeight | string | No | — | — |
| variants.steps.content_v2.width | string | No | — | — |
| variants.steps.sort_key | integer | No | — | Ignored on input. Steps are shown in the order of `steps`. Constraints: nullable |
| variants.translations | object | No | {"fr":{"steps[123].title":"Bienvenue","steps[123].blocks[3f0c1d2e-0000-4000-8000-000000000001].content.markdown":"Ravi de vous voir."},"de":null} | Locale (one of `localization.locales`) to translation key to text. Merged into the stored translations: keys you leave out are kept, `null` clears a key, and `null` for a locale clears every key in it. Keys name a field by where it sits in the variant: `display_title`, `display_description`, `snooze_label`, `done_label`; `steps[<step id>].title`; and block fields as `steps[<step id>].blocks[<block uuid>].<field>`, for example `content.markdown`, `content.title`, `content.button[primary]`, `content.survey_rating.lowerLabel`, or `content.survey_list`. Copy keys from `translation_status.sources` instead of building them. A key must name a field that has default-locale text. |
| latest_version | integer | Yes | — | Expected `latest_version` from the last GET with `include_unpublished_changes=true`. |

## Response (application/json)

**200** — Survey updated.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| data | object | Yes | — | — |
| data.id | string | Yes | — | Numeric nudge identifier. Constraints: pattern: ^[0-9]+$ |
| data.object | string | Yes | — | — |
| data.project_id | string | Yes | — | Constraints: pattern: ^[0-9]+$ |
| data.type | string | Yes | — | — |
| data.platform | string | Yes | — | Target platform. Guides and surveys without an explicit platform are returned as `web`. Allowed values: web, ios, android, react-native, desktop, flutter |
| data.title | string | Yes | — | Constraints: nullable |
| data.description | string | No | — | Constraints: nullable |
| data.is_archived | boolean | Yes | — | — |
| data.priority | integer | Yes | — | Trigger precedence (4 = urgent, 1 = low). Constraints: min: 1, max: 4 |
| data.status | string | Yes | — | Derived rollout state. Read-only on API responses. Allowed values: draft, published, testing, scheduled, scheduled-active, scheduled-inactive, experiment-running, experiment-inactive, archived |
| data.status_description | string | Yes | — | — |
| data.key | string | Yes | — | Feature flag key that controls delivery. Matches the `[Guides-Surveys] Key` property on SDK-tracked guide and survey events, so use it to join events to this guide or survey. Constraints: nullable |
| data.start_at | string | Yes | — | Scheduled start of the live flag. `null` when no start is scheduled. Constraints: format: date-time, nullable |
| data.end_at | string | Yes | — | Scheduled end of the live flag. `null` when no end is scheduled. Constraints: format: date-time, nullable |
| data.url | string | Yes | — | Admin URL for the guide or survey. Constraints: format: uri |
| data.page_target_segments | object[] | No | — | Pages where the guide or survey is eligible. Empty means every page. |
| data.page_target_segments.url | string | Yes | — | Page URL or pattern for the URL match types. |
| data.page_target_segments.matchType | string | Yes | — | Allowed values: simple, exact, pattern, contains, startsWith, endsWith, regex, domSelector |
| data.page_target_segments.isExclude | boolean | Yes | — | When true, matching pages are excluded. |
| data.page_target_segments.operator | string | No | — | How this rule combines with the next one. Allowed values: and, or |
| data.page_target_segments.value | string | No | — | CSS selector of an element that must be on the page. Required for `domSelector`, which is web only. |
| data.tags | string[] | No | — | — |
| data.created_by | string | No | — | Constraints: nullable |
| data.last_modified_by | string | No | — | Constraints: nullable |
| data.created_at | string | Yes | — | Constraints: format: date-time, nullable |
| data.updated_at | string | Yes | — | Constraints: format: date-time, nullable |
| data.latest_version | integer | Yes | — | Monotonic version for optimistic concurrency. Send the value from the latest GET on PATCH; a stale value returns 409. |
| data.temporarily_hide_page_target_segments | object[] | No | — | Page rules that are saved but not currently applied. |
| data.temporarily_hide_page_target_segments.url | string | Yes | — | Page URL or pattern for the URL match types. |
| data.temporarily_hide_page_target_segments.matchType | string | Yes | — | Allowed values: simple, exact, pattern, contains, startsWith, endsWith, regex, domSelector |
| data.temporarily_hide_page_target_segments.isExclude | boolean | Yes | — | When true, matching pages are excluded. |
| data.temporarily_hide_page_target_segments.operator | string | No | — | How this rule combines with the next one. Allowed values: and, or |
| data.temporarily_hide_page_target_segments.value | string | No | — | CSS selector of an element that must be on the page. Required for `domSelector`, which is web only. |
| data.hide_if_page_targeting_not_met | boolean | No | — | — |
| data.trigger_config | oneOf | No | — | When the guide or survey appears. One trigger, or an array of triggers where any match fires it. Nested keys keep their stored names (`selector`, `event`, `event_count`, `delay`, `filters`). Don't send `null`: the dashboard can't open a guide or survey without a trigger. Send `{"type": "immediately"}` to show right away. Constraints: oneOf (object), oneOf[] |
| data.trigger_config.type | string | No | — | Allowed values: immediately, none, smart_delay, rage_click, user_confusion, exit_intent, element_appeared, element_clicked |
| data.trigger_config.data | object | No | — | — |
| data.trigger_config.data.delay | number | No | — | Milliseconds to wait after the trigger fires. Omit it rather than sending null. Constraints: min: 0 |
| data.trigger_config.data.sessionPropertyFilters | object[][] | No | — | Session property conditions. The inner arrays are AND groups, and the outer array ORs them. |
| data.trigger_config.data.selector | string | No | — | CSS selector of the element. |
| data.trigger_config.data.event | string | No | — | Analytics event type that fires the trigger. |
| data.trigger_config.data.event_count | integer | No | — | Times the event must occur. Omitted means once. Constraints: min: 1 |
| data.trigger_config.data.filters | object[] | No | — | Event property conditions. Every condition must match. |
| data.trigger_config.data.filters.subprop_key | string | Yes | — | Property name. Constraints: min length: 1 |
| data.trigger_config.data.filters.subprop_op | string | Yes | — | Comparison operator, for example `is`, `is not`, or `contains`. |
| data.trigger_config.data.filters.subprop_value | string[] | Yes | — | Values to compare against. |
| data.trigger_config.data.filters.subprop_type | string | No | — | Property type, for example `event` or `user`. Constraints: nullable |
| data.trigger_config.data.filters.group_type | string | No | — | Constraints: nullable |
| data.trigger_config.data.unit | string | No | — | Allowed values: second, minute |
| data.trigger_config.data.value | number | No | — | How long to wait on the page before showing. |
| data.lifecycle | object | No | — | How often the guide or survey may show again. `periodCount` is camelCase; the other keys are snake_case. Send the whole object, not `null`. |
| data.lifecycle.stop_showing_if_completed | boolean | Yes | — | — |
| data.lifecycle.stop_showing_if_dismissed | boolean | Yes | — | — |
| data.lifecycle.survey_response_cap | object | No | — | — |
| data.lifecycle.survey_response_cap.enabled | boolean | No | — | — |
| data.lifecycle.survey_response_cap.value | integer | No | — | Stop after this many survey responses. Required when `enabled` is true. Constraints: min: 1 |
| data.lifecycle.cooldown_limits | object[] | Yes | — | — |
| data.lifecycle.cooldown_limits.max | integer | Yes | — | Maximum impressions in the period. Constraints: min: 1 |
| data.lifecycle.cooldown_limits.periodCount | integer | No | — | How many `period`s the limit covers. Omitted means 1. Constraints: min: 1 |
| data.lifecycle.cooldown_limits.period | string | Yes | — | Allowed values: day, week, month, year, session |
| data.lifecycle.even_distribution | object | No | — | — |
| data.lifecycle.even_distribution.enabled | boolean | Yes | — | — |
| data.lifecycle.even_distribution.recurrence_period_days | integer | Yes | — | Days over which impressions are spread evenly. Always required when `even_distribution` is sent. Constraints: min: 1 |
| data.dismissible | boolean | No | — | — |
| data.snoozable | boolean | No | — | — |
| data.snoozable_on_all_steps | boolean | No | — | — |
| data.snooze_duration | object | No | — | How long a snooze lasts. |
| data.snooze_duration.interval | string | Yes | — | Allowed values: hour, day, week |
| data.snooze_duration.value | number | Yes | — | Number of intervals. |
| data.snooze_label | string | No | — | Constraints: nullable |
| data.template_source | string | No | — | Constraints: nullable |
| data.show_step_counter | boolean | No | — | — |
| data.step_counter_format | string | No | — | Constraints: nullable |
| data.theme_id | string | No | — | Theme applied to this guide or survey. `null` means the project's default theme for the platform. Fetch it with the Themes API. Constraints: nullable, pattern: ^[0-9]+$ |
| data.variants | object[] | No | — | — |
| data.variants.id | string | Yes | — | — |
| data.variants.variant | string | Yes | — | Variant key within the nudge: lowercase letters, digits, `-` and `_`. Keys must be unique. `off` is reserved, and `control` can't be given to a new variant. Constraints: pattern: ^[a-z0-9_-]+$ |
| data.variants.display_title | string | No | — | Constraints: nullable |
| data.variants.display_description | string | No | — | Constraints: nullable |
| data.variants.snooze_label | string | No | — | Constraints: nullable, max length: 255 |
| data.variants.done_label | string | No | — | Constraints: nullable, max length: 255 |
| data.variants.steps | object[] | No | — | — |
| data.variants.steps.id | string | Yes | — | — |
| data.variants.steps.title | string | No | — | Constraints: nullable, max length: 255 |
| data.variants.steps.form_factor | oneOf | No | — | Step layout. `type` selects it. Every form factor also accepts `zIndexOverride` (number or null) and `textAnimation` (`typewriter`). Modal, popover, pin, tooltip, and card accept the step layout keys `layout`, `mediaPosition`, `contentAlignment`, `titleAlignment`, and `footerLayout`; banner and checklist accept a narrower set. Tooltips and cards can't be snoozed. Constraints: object |
| data.variants.steps.form_factor.type | string | Yes | — | — |
| data.variants.steps.form_factor.position | string | No | — | Where a modal or popover sits in the viewport. Allowed values: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right, left-center, right-center, center, top, bottom, auto, left, right, prepend, append, replace, before, after |
| data.variants.steps.form_factor.canClickOutsideToClose | boolean | No | — | — |
| data.variants.steps.form_factor.fullWidthModal | boolean | No | — | — |
| data.variants.steps.form_factor.layout | string | No | — | Arrangement of media and text in the step. Allowed values: classic, vertical, showcase, horizontal |
| data.variants.steps.form_factor.mediaPosition | string | No | — | Media side for the `horizontal` layout. Allowed values: left, right |
| data.variants.steps.form_factor.contentAlignment | string | No | — | Allowed values: start, center, end |
| data.variants.steps.form_factor.titleAlignment | string | No | — | Allowed values: start, center, end |
| data.variants.steps.form_factor.footerLayout | string | No | — | Arrangement of the step's buttons. Allowed values: classic, split, centered, stacked |
| data.variants.steps.form_factor.placement | string | No | — | Allowed values: default, overlay |
| data.variants.steps.form_factor.sticky | boolean | No | — | Keep the banner on screen while the page scrolls. |
| data.variants.steps.form_factor.anchor | string | No | — | CSS selector the pin attaches to. |
| data.variants.steps.form_factor.anchorSelector | object | No | — | Richer element match used alongside `anchor`. |
| data.variants.steps.form_factor.anchorSelector.selector | string | Yes | — | — |
| data.variants.steps.form_factor.anchorSelector.text | string | Yes | — | Visible text of the element. |
| data.variants.steps.form_factor.anchorSelector.tag | string | Yes | — | HTML tag name. |
| data.variants.steps.form_factor.anchorSelector.attributes | object | Yes | — | — |
| data.variants.steps.form_factor.anchorSelector.strategy | string | No | — | Allowed values: strict, fallback, selector_only |
| data.variants.steps.form_factor.alignment | string | No | — | Allowed values: center, top, bottom, left, right, start, end |
| data.variants.steps.form_factor.offset | object | No | — | Both `x` and `y` are required. |
| data.variants.steps.form_factor.offset.x | string | Yes | — | CSS length, for example `0px`. |
| data.variants.steps.form_factor.offset.y | string | Yes | — | CSS length, for example `0px`. |
| data.variants.steps.form_factor.pointer | object | No | — | — |
| data.variants.steps.form_factor.pointer.type | string | Yes | — | Allowed values: beacon, arrow, none |
| data.variants.steps.form_factor.isOpenByDefault | boolean | No | — | — |
| data.variants.steps.form_factor.openOnHover | boolean | No | — | — |
| data.variants.steps.form_factor.isShowingMask | boolean | No | — | Dim the rest of the page. |
| data.variants.steps.form_factor.advanceTrigger | string | No | — | CSS selector whose click advances to the next step. |
| data.variants.steps.form_factor.disableAutoAdvanceOnClick | boolean | No | — | — |
| data.variants.steps.form_factor.skipIfNotFound | boolean | No | — | Skip the step when the anchor is missing. |
| data.variants.steps.form_factor.showOn | string | No | — | Allowed values: hover, click |
| data.variants.steps.form_factor.marker | oneOf | No | — | The marker users hover or click to open the tooltip. Every marker type also accepts `width` (number) and `elementIsMarker` (boolean). Constraints: object |
| data.variants.steps.form_factor.marker.type | string | Yes | — | — |
| data.variants.steps.form_factor.marker.positioning | object | Yes | — | — |
| data.variants.steps.form_factor.marker.positioning.position | string | Yes | — | Allowed values: left, right, inline_left, inline_right |
| data.variants.steps.form_factor.marker.positioning.offset | object | Yes | — | Both `x` and `y` are required. |
| data.variants.steps.form_factor.marker.positioning.offset.x | string | Yes | — | CSS length, for example `0px`. |
| data.variants.steps.form_factor.marker.positioning.offset.y | string | Yes | — | CSS length, for example `0px`. |
| data.variants.steps.form_factor.marker.icon | string | No | — | Allowed values: helpCircle, helpSquare, infoCircle, bookClosed, lightBulb, lightning |
| data.variants.steps.form_factor.marker.source | string | No | — | Image URL. |
| data.variants.steps.form_factor.cardWidth | object | No | — | — |
| data.variants.steps.form_factor.cardWidth.type | string | Yes | — | Allowed values: auto, fixed, full |
| data.variants.steps.form_factor.cardWidth.value | number | No | — | Pixels, used with `fixed`. |
| data.variants.steps.form_factor.cardHeight | object | No | — | — |
| data.variants.steps.form_factor.cardHeight.type | string | Yes | — | Allowed values: auto, fixed, full |
| data.variants.steps.form_factor.cardHeight.value | number | No | — | Pixels, used with `fixed`. |
| data.variants.steps.form_factor.cardMargin | object | No | — | — |
| data.variants.steps.form_factor.cardMargin.top | number | Yes | — | — |
| data.variants.steps.form_factor.cardMargin.right | number | Yes | — | — |
| data.variants.steps.form_factor.cardMargin.bottom | number | Yes | — | — |
| data.variants.steps.form_factor.cardMargin.left | number | Yes | — | — |
| data.variants.steps.content | oneOf[] | No | [{"uuid":"3f0c2a8e-5b1d-4c7a-9e2f-1a6b8d4c0e11","type":"markdown","meta":{"value":"Track any event in two clicks."}},{"uuid":"8d2e6f1a-7c3b-4e9d-a0f5-2b7c9e1d3a42","type":"button","meta":{"label":"Next","buttonType":"primary","action":{"type":"step_forward"}}}] | The step body: content blocks rendered top to bottom, below the step `title`. `meta` keys are camelCase. Keep a block's existing `uuid` when you edit it, because survey responses are keyed by it; a block sent without one (or with `null`) is given one on save. To change one block, send the step's whole `content` array back with that block edited. Send `[]` for an empty step, not `null`. A step can have at most one `markdown` block, one `image` or one `video` (not both), two buttons, ten survey questions, and ten `survey_hidden` fields. Survey question blocks are only allowed in surveys, and only on steps with the `classic` or `vertical` layout. A checklist item can have at most one button. A snooze button needs the variant's `snooze_label`. |
| data.variants.steps.content.uuid | string | No | — | Constraints: nullable |
| data.variants.steps.content.type | string | Yes | — | `survey_text` is a multi-line answer; `survey_text_short` is a single line. Allowed values: survey_text, survey_text_short |
| data.variants.steps.content.meta | object | Yes | — | — |
| data.variants.steps.content.meta.value | string | No | — | Markdown text. Inline HTML is allowed and is sanitized on save. |
| data.variants.steps.content.meta.alignment | string | No | — | Allowed values: start, center, end |
| data.variants.steps.content.meta.textAnimation | string | No | — | — |
| data.variants.steps.content.meta.src | string | No | — | Image URL. |
| data.variants.steps.content.meta.filename | string | No | — | — |
| data.variants.steps.content.meta.size | string | No | — | — |
| data.variants.steps.content.meta.altText | string | No | — | — |
| data.variants.steps.content.meta.style | object | No | — | — |
| data.variants.steps.content.meta.style.scale | string | No | — | — |
| data.variants.steps.content.meta.style.radius | string | No | — | — |
| data.variants.steps.content.meta.style.fit | string | No | — | Allowed values: cover, contain |
| data.variants.steps.content.meta.style.height | string | No | — | — |
| data.variants.steps.content.meta.action | object | No | {"type":"link","value":"https://example.com/pricing","operation":"blank"} | Optional link opened when the image is clicked. No other action type is allowed. |
| data.variants.steps.content.meta.action.type | string | Yes | — | Common actions: - `step_forward`, `step_back`: go to the next or previous step. - `complete`: finish the guide or survey. - `dismiss`: close it. - `snooze`: hide it for a while, with optional `interval` (`hour`, `day`, `week`) and `value`. - `go_to_step`: jump to a step. `value` is the 0-based position of the step in the variant's `steps`, not its id. - `link`: open the URL in `value`; `operation` is `self` (same tab), `blank` (new tab) or `router`. - `nudge`: start another guide or survey. `value` is its numeric id, and `productType` is `guide` or `survey`. - `no_action`: no action of its own. The button still advances: to the next step, or on the last step it finishes the guide or survey. The dashboard's survey templates use it for the submit button. It does not keep the user on the step; `stay_on_step` does. Buttons built in the dashboard can also use `stay_on_step`, `click` (`value` is a CSS selector), `callback`, `app_review`, `open_resource_center`, `open_ai_assistant`, `open_chat`, `document`, `video`, and `use_conditional_logic`. Send those back unchanged. |
| data.variants.steps.content.meta.action.value | string | No | — | URL to open. |
| data.variants.steps.content.meta.action.operation | string | No | — | Allowed values: self, blank, router |
| data.variants.steps.content.meta.type | string | No | — | `nps` is a 0–10 scale and takes `options: 10`. Allowed values: stars, numbers, emojis, nps |
| data.variants.steps.content.meta.label | string | No | — | — |
| data.variants.steps.content.meta.buttonType | string | No | — | Allowed values: primary, secondary, snooze |
| data.variants.steps.content.meta.grow | boolean | No | — | Stretch the button to fill the footer row. |
| data.variants.steps.content.meta.width | string | No | — | CSS width, for example `100%`. |
| data.variants.steps.content.meta.actions | object | No | — | Optional action sequence the dashboard writes for buttons with side effects: `{type: "action_sequence", navigation: <action>, effects: [<action>]}`. When present, the SDK runs it instead of `action`, so update both or neither. |
| data.variants.steps.content.meta.prompt | string | No | — | Placeholder shown in the empty answer field. Required; send `""` for none. |
| data.variants.steps.content.meta.ariaLabel | string | No | — | — |
| data.variants.steps.content.meta.prefill | object | No | — | `survey_text_short` only. |
| data.variants.steps.content.meta.prefill.enabled | boolean | Yes | — | — |
| data.variants.steps.content.meta.prefill.userProperty | string | Yes | — | User property whose value fills the answer. |
| data.variants.steps.content.meta.validation | object | No | — | — |
| data.variants.steps.content.meta.validation.required | object | No | — | — |
| data.variants.steps.content.meta.validation.required.value | boolean | Yes | — | — |
| data.variants.steps.content.meta.validation.required.message | string | No | — | Error shown when a required question is left empty. Required when `value` is `true`. Constraints: nullable |
| data.variants.steps.content.meta.options | array or integer | No | — | Number of choices on the scale. Allowed values depend on `type`: `stars` 3 or 5, `numbers` 3, 5, 7 or 10, `emojis` 2, 3 or 5, and `nps` 10. |
| data.variants.steps.content.meta.listType | string | No | — | Allowed values: single, multiple |
| data.variants.steps.content.meta.displayType | string | No | — | Allowed values: list, dropdown, grid |
| data.variants.steps.content.meta.isOrderRandom | boolean | No | — | — |
| data.variants.steps.content.meta.otherOption | object | No | — | — |
| data.variants.steps.content.meta.otherOption.enabled | boolean | Yes | — | — |
| data.variants.steps.content.meta.otherOption.label | string | Yes | — | — |
| data.variants.steps.content.meta.otherOption.placeholderLabel | string | Yes | — | — |
| data.variants.steps.content.meta.emojis | string[] | No | — | Exactly one emoji per option. Required when `type` is `emojis`. |
| data.variants.steps.content.meta.lowerLabel | string | No | — | — |
| data.variants.steps.content.meta.upperLabel | string | No | — | — |
| data.variants.steps.content.meta.source | oneOf | No | — | Constraints: object |
| data.variants.steps.content.meta.source.type | string | Yes | — | — |
| data.variants.steps.content.meta.source.value | string | No | — | The value to record. |
| data.variants.steps.content.meta.source.property | string | No | — | Property of the event that triggered the survey. |
| data.variants.steps.content_v2 | oneOf | No | — | Block-builder layout: a tree of `layout` containers whose `children` are containers or content blocks, including the step's `title` block. Returned only on steps built in the block builder; when present, the dashboard and SDK render this tree, not `title` and `content`. On update, only accepted on resources that already have a step with a tree; a flat-only guide or survey can't be converted through the API. On create, any step may take one, so a resource read with `content_v2` can be copied. Block `uuid`s must be unique within the step. Keep a block's existing `uuid` when you edit it, because survey responses are keyed by it; a block sent without one is given one on save. The saved tree is normalized to the shape the block builder saves, and the step title is taken from its `title` block. On a step with a tree, send `title` and `content` only together with `content_v2`. Not supported on banner or checklist steps or on mobile platforms. `null` switches the step back to `content`. Constraints: object, null |
| data.variants.steps.content_v2.type | string | No | — | — |
| data.variants.steps.content_v2.children | oneOf[] | No | — | — |
| data.variants.steps.content_v2.children.uuid | string | No | — | Constraints: nullable |
| data.variants.steps.content_v2.children.type | string | No | — | `survey_text` is a multi-line answer; `survey_text_short` is a single line. Allowed values: survey_text, survey_text_short |
| data.variants.steps.content_v2.children.meta | object | No | — | — |
| data.variants.steps.content_v2.children.meta.value | string | No | — | Markdown text. Inline HTML is allowed and is sanitized on save. |
| data.variants.steps.content_v2.children.meta.alignment | string | No | — | Allowed values: start, center, end |
| data.variants.steps.content_v2.children.meta.textAnimation | string | No | — | — |
| data.variants.steps.content_v2.children.meta.src | string | No | — | Image URL. |
| data.variants.steps.content_v2.children.meta.filename | string | No | — | — |
| data.variants.steps.content_v2.children.meta.size | string | No | — | — |
| data.variants.steps.content_v2.children.meta.altText | string | No | — | — |
| data.variants.steps.content_v2.children.meta.style | object | No | — | — |
| data.variants.steps.content_v2.children.meta.style.scale | string | No | — | — |
| data.variants.steps.content_v2.children.meta.style.radius | string | No | — | — |
| data.variants.steps.content_v2.children.meta.style.fit | string | No | — | Allowed values: cover, contain |
| data.variants.steps.content_v2.children.meta.style.height | string | No | — | — |
| data.variants.steps.content_v2.children.meta.action | object | No | {"type":"link","value":"https://example.com/pricing","operation":"blank"} | Optional link opened when the image is clicked. No other action type is allowed. |
| data.variants.steps.content_v2.children.meta.action.type | string | Yes | — | Common actions: - `step_forward`, `step_back`: go to the next or previous step. - `complete`: finish the guide or survey. - `dismiss`: close it. - `snooze`: hide it for a while, with optional `interval` (`hour`, `day`, `week`) and `value`. - `go_to_step`: jump to a step. `value` is the 0-based position of the step in the variant's `steps`, not its id. - `link`: open the URL in `value`; `operation` is `self` (same tab), `blank` (new tab) or `router`. - `nudge`: start another guide or survey. `value` is its numeric id, and `productType` is `guide` or `survey`. - `no_action`: no action of its own. The button still advances: to the next step, or on the last step it finishes the guide or survey. The dashboard's survey templates use it for the submit button. It does not keep the user on the step; `stay_on_step` does. Buttons built in the dashboard can also use `stay_on_step`, `click` (`value` is a CSS selector), `callback`, `app_review`, `open_resource_center`, `open_ai_assistant`, `open_chat`, `document`, `video`, and `use_conditional_logic`. Send those back unchanged. |
| data.variants.steps.content_v2.children.meta.action.value | string | No | — | URL to open. |
| data.variants.steps.content_v2.children.meta.action.operation | string | No | — | Allowed values: self, blank, router |
| data.variants.steps.content_v2.children.meta.type | string | No | — | `nps` is a 0–10 scale and takes `options: 10`. Allowed values: stars, numbers, emojis, nps |
| data.variants.steps.content_v2.children.meta.label | string | No | — | — |
| data.variants.steps.content_v2.children.meta.buttonType | string | No | — | Allowed values: primary, secondary, snooze |
| data.variants.steps.content_v2.children.meta.grow | boolean | No | — | Stretch the button to fill the footer row. |
| data.variants.steps.content_v2.children.meta.width | string | No | — | CSS width, for example `100%`. |
| data.variants.steps.content_v2.children.meta.actions | object | No | — | Optional action sequence the dashboard writes for buttons with side effects: `{type: "action_sequence", navigation: <action>, effects: [<action>]}`. When present, the SDK runs it instead of `action`, so update both or neither. |
| data.variants.steps.content_v2.children.meta.prompt | string | No | — | Placeholder shown in the empty answer field. Required; send `""` for none. |
| data.variants.steps.content_v2.children.meta.ariaLabel | string | No | — | — |
| data.variants.steps.content_v2.children.meta.prefill | object | No | — | `survey_text_short` only. |
| data.variants.steps.content_v2.children.meta.prefill.enabled | boolean | Yes | — | — |
| data.variants.steps.content_v2.children.meta.prefill.userProperty | string | Yes | — | User property whose value fills the answer. |
| data.variants.steps.content_v2.children.meta.validation | object | No | — | — |
| data.variants.steps.content_v2.children.meta.validation.required | object | No | — | — |
| data.variants.steps.content_v2.children.meta.validation.required.value | boolean | Yes | — | — |
| data.variants.steps.content_v2.children.meta.validation.required.message | string | No | — | Error shown when a required question is left empty. Required when `value` is `true`. Constraints: nullable |
| data.variants.steps.content_v2.children.meta.options | array or integer | No | — | Number of choices on the scale. Allowed values depend on `type`: `stars` 3 or 5, `numbers` 3, 5, 7 or 10, `emojis` 2, 3 or 5, and `nps` 10. |
| data.variants.steps.content_v2.children.meta.listType | string | No | — | Allowed values: single, multiple |
| data.variants.steps.content_v2.children.meta.displayType | string | No | — | Allowed values: list, dropdown, grid |
| data.variants.steps.content_v2.children.meta.isOrderRandom | boolean | No | — | — |
| data.variants.steps.content_v2.children.meta.otherOption | object | No | — | — |
| data.variants.steps.content_v2.children.meta.otherOption.enabled | boolean | Yes | — | — |
| data.variants.steps.content_v2.children.meta.otherOption.label | string | Yes | — | — |
| data.variants.steps.content_v2.children.meta.otherOption.placeholderLabel | string | Yes | — | — |
| data.variants.steps.content_v2.children.meta.emojis | string[] | No | — | Exactly one emoji per option. Required when `type` is `emojis`. |
| data.variants.steps.content_v2.children.meta.lowerLabel | string | No | — | — |
| data.variants.steps.content_v2.children.meta.upperLabel | string | No | — | — |
| data.variants.steps.content_v2.children.meta.source | oneOf | No | — | Constraints: object |
| data.variants.steps.content_v2.children.meta.source.type | string | Yes | — | — |
| data.variants.steps.content_v2.children.meta.source.value | string | No | — | The value to record. |
| data.variants.steps.content_v2.children.meta.source.property | string | No | — | Property of the event that triggered the survey. |
| data.variants.steps.content_v2.children.meta.format | string | No | — | Allowed values: numeric, verbose |
| data.variants.steps.content_v2.id | string | No | — | Container id, unique within the step. |
| data.variants.steps.content_v2.direction | string | No | — | Allowed values: row, column |
| data.variants.steps.content_v2.justify | string | No | — | Allowed values: start, center, end, space-between, space-around |
| data.variants.steps.content_v2.align | string | No | — | Allowed values: start, center, end |
| data.variants.steps.content_v2.gap | string | No | — | CSS length, for example `8px`. |
| data.variants.steps.content_v2.padding | string | No | — | — |
| data.variants.steps.content_v2.margin | string | No | — | — |
| data.variants.steps.content_v2.pinned | boolean | No | — | — |
| data.variants.steps.content_v2.wrap | boolean | No | — | — |
| data.variants.steps.content_v2.overflow | string | No | — | Allowed values: auto, hidden |
| data.variants.steps.content_v2.minHeight | string | No | — | — |
| data.variants.steps.content_v2.width | string | No | — | — |
| data.variants.steps.sort_key | integer | No | — | Constraints: nullable |
| data.variants.translations | object | No | — | Stored translations, locale to translation key to text. Returned with `include_translations=true` and on updates that send translations. |
| data.variants.translation_status | object | No | — | What is left to translate. `sources` lists every translatable key with its current default-locale text. Per locale, `missing` keys have no translation and `outdated` keys were translated from text that has since changed. |
| data.variants.translation_status.sources | object | Yes | — | — |
| data.variants.translation_status.locales | object | Yes | — | — |
| data.experiment_variants | object[] | No | — | Read-only experiment variant keys when the nudge is experiment-backed. |
| data.experiment_variants.key | string | Yes | — | — |
| data.experiment_variants.name | string | No | — | Constraints: nullable |
| data.experiment_variants.description | string | No | — | Constraints: nullable |
| data.experiment_variants.payload | unknown | No | — | Optional JSON payload associated with the experiment variant. |
| data.flag_config | oneOf | No | — | The Experiment feature flag that delivers this nudge, in the same shape as the Feature Flags API. Includes audience targeting (`target_segments`) and rollout. With `include_unpublished_changes=true`, draft rollout and targeting settings are applied over the live flag. Constraints: object, null |
| data.flag_config.id | string | No | — | — |
| data.flag_config.project_id | string | No | — | Constraints: pattern: ^[0-9]+$ |
| data.flag_config.key | string | No | — | — |
| data.flag_config.name | string | No | — | — |
| data.flag_config.description | string | No | — | Constraints: nullable |
| data.flag_config.deployments | string[] | No | — | Deployment IDs associated with this flag. Managed via the create/update deployment fields, not set directly on this field. |
| data.flag_config.enabled | boolean | No | — | — |
| data.flag_config.evaluation_mode | string | No | — | Allowed values: local, remote |
| data.flag_config.variants | object[] | No | — | — |
| data.flag_config.variants.key | string | Yes | — | Stable variant key. The value `off` is reserved. Constraints: pattern: ^[A-Za-z0-9_-]+$ |
| data.flag_config.variants.name | string | No | — | Constraints: nullable |
| data.flag_config.variants.description | string | No | — | Constraints: nullable |
| data.flag_config.variants.payload | unknown | No | — | Optional JSON payload returned by evaluation. |
| data.flag_config.bucketing_key | string | No | — | Bucketing key used for assignment. Never null in responses; defaults to `amplitude_id` when not explicitly set. |
| data.flag_config.bucketing_salt | string | No | — | Constraints: nullable |
| data.flag_config.bucketing_unit | string | No | — | Constraints: nullable |
| data.flag_config.rollout_percentage | integer | No | — | Constraints: min: 0, max: 100 |
| data.flag_config.rollout_weights | object | No | — | Variant-keyed rollout weights. Values may be normalized to sum to 100 (percentages) or expressed as unnormalized relative weights (for example `{ "control": 1, "treatment": 1 }` for an even split). Weights are non-negative and may be fractional. |
| data.flag_config.target_segments | object[] | No | — | — |
| data.flag_config.target_segments.name | string | No | — | Constraints: nullable |
| data.flag_config.target_segments.conditions | object[] | Yes | — | — |
| data.flag_config.target_segments.conditions.group_type | string | No | — | Constraints: nullable |
| data.flag_config.target_segments.conditions.prop | string | Yes | — | Property name or cohort identifier being targeted. Constraints: min length: 1 |
| data.flag_config.target_segments.conditions.prop_type | string | No | — | Namespace of the targeted property, for example `user`, `event`, or `group`. Omitted for conditions that target a cohort rather than a property. Constraints: nullable |
| data.flag_config.target_segments.conditions.op | string | Yes | — | Targeting operator applied to the property values. Allowed values: is, is not, contains, does not contain, less, less or equal, greater, greater or equal, set is, set is not, set contains, set does not contain, glob match, glob does not match |
| data.flag_config.target_segments.conditions.type | string | Yes | — | Condition type, for example `property` or `cohort`. |
| data.flag_config.target_segments.conditions.values | string[] | Yes | — | At least one value to match against. Conditions with no values are rejected. |
| data.flag_config.target_segments.percentage | integer | No | — | Segment rollout percentage. Constraints: nullable, min: 0, max: 100 |
| data.flag_config.target_segments.rollout_weights | object | No | — | Variant-keyed rollout weights. Values may be normalized to sum to 100 (percentages) or expressed as unnormalized relative weights (for example `{ "control": 1, "treatment": 1 }` for an even split). Weights are non-negative and may be fractional. |
| data.flag_config.target_segments.bucketing_key | string | No | — | Constraints: nullable |
| data.flag_config.testers | object[] | No | — | — |
| data.flag_config.testers.variant_key | string | Yes | — | — |
| data.flag_config.testers.values | string[] | Yes | — | User IDs, device IDs, or cohort identifiers included in this variant. At most 2000 entries per variant (the limit is 10 when the entries are cohort identifiers). |
| data.flag_config.owners | string[] | No | — | — |
| data.flag_config.tags | string[] | No | — | — |
| data.flag_config.created_by | string | No | — | Constraints: nullable |
| data.flag_config.last_modified_by | string | No | — | Constraints: nullable |
| data.flag_config.created_at | string | No | — | Constraints: format: date-time, nullable |
| data.flag_config.updated_at | string | No | — | Constraints: format: date-time, nullable |
| data.flag_config.parent_dependencies | object | No | — | — |
| data.flag_config.parent_dependencies.operator | string | Yes | — | Allowed values: all, any |
| data.flag_config.parent_dependencies.flags | object[] | Yes | — | — |
| data.flag_config.parent_dependencies.flags.flag_id | string | Yes | — | — |
| data.flag_config.parent_dependencies.flags.allowed_variants | string[] | No | — | — |
| data.flag_config.links | object[] | No | — | — |
| data.flag_config.links.url | string | Yes | — | Constraints: format: uri |
| data.flag_config.links.title | string | Yes | — | — |
| data.flag_config.version | integer | No | — | Server-managed config version used for optimistic concurrency. |
| data.flag_config.archived | boolean | No | — | Whether the resource is archived. Set via the archive (DELETE) operation. |
| data.flag_config.url | string | No | — | Constraints: format: uri, nullable |
| data.flag_config.object | string | No | — | Resource-type discriminator. Always `feature_flag`. |
| data.localization | object | No | — | The project's localization settings. `locales` are the languages other than `default_locale` that translations can be written for. Configure them in project settings. When localization is disabled, only `enabled: false` is returned and variants carry no `translations` or `translation_status`. |
| data.localization.enabled | boolean | Yes | — | — |
| data.localization.default_locale | string | No | — | — |
| data.localization.locales | string[] | No | — | — |

```json
{
  "data": {
    "id": "string",
    "object": "survey",
    "project_id": "string",
    "type": "SURVEY",
    "platform": "web",
    "title": "string",
    "description": "string",
    "is_archived": true,
    "priority": 1,
    "status": "draft",
    "status_description": "string",
    "key": "string",
    "start_at": "2024-01-01T00:00:00Z",
    "end_at": "2024-01-01T00:00:00Z",
    "url": "https://example.com",
    "page_target_segments": [
      {
        "url": "string",
        "matchType": "simple",
        "isExclude": true,
        "operator": "and",
        "value": "string"
      }
    ],
    "tags": [
      "string"
    ],
    "created_by": "string",
    "last_modified_by": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "latest_version": 0,
    "temporarily_hide_page_target_segments": [
      {
        "url": "string",
        "matchType": "simple",
        "isExclude": true,
        "operator": "and",
        "value": "string"
      }
    ],
    "hide_if_page_targeting_not_met": true,
    "trigger_config": {
      "type": "immediately"
    },
    "lifecycle": {
      "stop_showing_if_completed": true,
      "stop_showing_if_dismissed": true,
      "survey_response_cap": {
        "enabled": true,
        "value": 1
      },
      "cooldown_limits": [
        {
          "max": 1,
          "periodCount": 1,
          "period": "day"
        }
      ],
      "even_distribution": {
        "enabled": true,
        "recurrence_period_days": 1
      }
    },
    "dismissible": true,
    "snoozable": true,
    "snoozable_on_all_steps": true,
    "snooze_duration": {
      "interval": "hour",
      "value": 0
    },
    "snooze_label": "string",
    "template_source": "string",
    "show_step_counter": true,
    "step_counter_format": "string",
    "theme_id": "string",
    "variants": [
      {
        "id": "string",
        "variant": "string",
        "display_title": "string",
        "display_description": "string",
        "snooze_label": "string",
        "done_label": "string",
        "steps": [
          {
            "id": "string",
            "title": "string",
            "form_factor": {
              "type": "modal",
              "position": "top-left",
              "canClickOutsideToClose": true,
              "fullWidthModal": true,
              "layout": "classic",
              "mediaPosition": "left",
              "contentAlignment": "start",
              "titleAlignment": "start",
              "footerLayout": "classic"
            },
            "content": [
              {
                "uuid": "3f0c2a8e-5b1d-4c7a-9e2f-1a6b8d4c0e11",
                "type": "markdown",
                "meta": {
                  "value": "Track any event in two clicks."
                }
              },
              {
                "uuid": "8d2e6f1a-7c3b-4e9d-a0f5-2b7c9e1d3a42",
                "type": "button",
                "meta": {
                  "label": "Next",
                  "buttonType": "primary",
                  "action": {
                    "type": "step_forward"
                  }
                }
              }
            ],
            "content_v2": {
              "type": "layout",
              "children": [
                null
              ],
              "id": "string",
              "direction": "row",
              "justify": "start",
              "align": "start",
              "gap": "string",
              "padding": "string",
              "margin": "string",
              "pinned": true,
              "wrap": true,
              "overflow": "auto",
              "minHeight": "string",
              "width": "string"
            },
            "sort_key": 0
          }
        ],
        "translations": {},
        "translation_status": {
          "sources": {},
          "locales": {}
        }
      }
    ],
    "experiment_variants": [
      {
        "key": "string",
        "name": "string",
        "description": "string",
        "payload": null
      }
    ],
    "flag_config": {
      "id": "string",
      "project_id": "string",
      "key": "string",
      "name": "string",
      "description": "string",
      "deployments": [
        "string"
      ],
      "enabled": true,
      "evaluation_mode": "local",
      "variants": [
        {
          "key": "string",
          "name": "string",
          "description": "string",
          "payload": null
        }
      ],
      "bucketing_key": "string",
      "bucketing_salt": "string",
      "bucketing_unit": "string",
      "rollout_percentage": 0,
      "rollout_weights": {},
      "target_segments": [
        {
          "name": "string",
          "conditions": [
            {
              "group_type": "string",
              "prop": "string",
              "prop_type": "string",
              "op": "is",
              "type": "string",
              "values": [
                "string"
              ]
            }
          ],
          "percentage": 0,
          "rollout_weights": {},
          "bucketing_key": "string"
        }
      ],
      "testers": [
        {
          "variant_key": "string",
          "values": [
            "string"
          ]
        }
      ],
      "owners": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "created_by": "string",
      "last_modified_by": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "parent_dependencies": {
        "operator": "all",
        "flags": [
          {
            "flag_id": "string",
            "allowed_variants": [
              "string"
            ]
          }
        ]
      },
      "links": [
        {
          "url": "https://example.com",
          "title": "string"
        }
      ],
      "version": 0,
      "archived": true,
      "url": "https://example.com",
      "object": "feature_flag"
    },
    "localization": {
      "enabled": true,
      "default_locale": "string",
      "locales": [
        "string"
      ]
    }
  }
}
```

**400**

**401**

**403**

**404**

**409**

**429**

**500**

## Code samples

### cURL

```bash
curl -X PATCH "https://developer-api.amplitude.com/v1/projects/12345/surveys/{survey_id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY"
```

### Python

```python
import requests

response = requests.patch(
    "https://developer-api.amplitude.com/v1/projects/12345/surveys/{survey_id}",
    headers={
        "Content-Type": "application/json",
        "Authorization": "YOUR_API_KEY"
    }
)
data = response.json()
```

### JavaScript

```javascript
const response = await fetch("https://developer-api.amplitude.com/v1/projects/12345/surveys/{survey_id}", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_KEY"
  }
});
const data = await response.json();
```

### PHP

```php
<?php
$ch = curl_init("https://developer-api.amplitude.com/v1/projects/12345/surveys/{survey_id}");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
```

### Go

```go
package main

import (
  "bytes"
  "net/http"
)

func main() {
req, _ := http.NewRequest("PATCH", "https://developer-api.amplitude.com/v1/projects/12345/surveys/{survey_id}", nil)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "YOUR_API_KEY")
  client := &http.Client{}
  resp, _ := client.Do(req)
  defer resp.Body.Close()
}
```

### Java

```java
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://developer-api.amplitude.com/v1/projects/12345/surveys/{survey_id}"))
      .method("PATCH", HttpRequest.BodyPublishers.noBody())
.header("Content-Type", "application/json")
      .header("Authorization", "YOUR_API_KEY")
      .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
```

### Ruby

```ruby
require "net/http"
require "json"

uri = URI("https://developer-api.amplitude.com/v1/projects/12345/surveys/{survey_id}")
request = Net::HTTP::Patch.new(uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "YOUR_API_KEY"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
```

