Update a survey

The authorization owner — the person whose restricted surveys these are. Distinct from creator, which is attribution only and is never rewritten. Display only, like creator: no user id is exposed, because access.via === "owner" already answers "is this mine" and filter[owner][in]=me filters server-side. Ownership transfer can add an identifier later, additively. Durable source: Survey.ownerId in PostgreSQL, projected to survey#owner@user; the graph never holds ownership alone, so a rebuild from an empty graph restores it.

Why this caller can see the survey, and whether they may change its visibility. Derived by the server per request; a rendering hint only — every mutation is re-authorised on the server.

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.

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.

Optional card shown before the first survey block.

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.

Naming rule for new field ids — the same rule the survey editor applies (ENG-2539): a new id must start with a lowercase letter and then contain only lowercase letters, numbers and underscores (^[a-z][a-z0-9_]*$), and must not take a reserved name. Reserved are the link-survey system params and internal ids — userId, source, suid, end, start, welcomeCard, hidden, verifiedEmail, multiLanguage, embed, verify, suToken, lang, preview, startAt, skipPrefilled, offlineSupport (matched case-insensitively) — and the names of auto-captured system fields, which every survey can already read without declaring them: source, url, country, action, browser, os, deviceType, ipAddress, finished, language, locale, responseId, surveyId, durationSeconds, startedAt, finishedAt, pagePath, pageReferrer, utmSource, utmMedium, utmCampaign, utmTerm, utmContent, screenWidth, screenHeight, viewportWidth, viewportHeight, timezone, visitPagesViewed, visitUniquePagesViewed, visitTimeOnSite, visitEntryReferrer, visitUrls, openedByCreativeId, openedByCreativeName.

Ids a survey already declares are grandfathered: they always load, and re-sending the survey unchanged never fails validation — only adding such a name as a new field is refused. Deleting a grandfathered field spends the reprieve: once it is gone from the saved survey, the name can no longer be re-added. Note this means re-creating a survey from an exported document can fail with a 400 when the export declares a name the rule refuses; rename the field in the payload before importing. The pattern below describes what stored surveys may hold (the pre-existing lenient charset), not what a new id may look like.

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.

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.

Custom CSS source as a caller writes it (ENG-3641). Both keys are required. light is base CSS that applies in both appearances; dark adds overrides on top of it when the survey renders dark. null, an empty string or whitespace means "no CSS" for that field. Source only: compiled output and the processor version are computed by the server on every write, and a request that supplies either is rejected. The combined source is limited to 100 000 UTF-8 bytes for a workspace and 20 000 for a survey; larger CSS is a 422 with error code source_too_large.

The three fields every SurveyListItem and SurveyResource carries, merged into both via allOf. All required, always present.

Processing warnings for this write: constructs the processor removed. Additive, returned beside data (never inside it, so data can be sent back unchanged); present only when the write processed custom CSS.