Skip to main content
POST

Authorizations

next-auth.session-token
string
cookie
required

NextAuth session JWT cookie. Development: often next-auth.session-token. Production (HTTPS): often __Secure-next-auth.session-token. Send the cookie your browser receives after sign-in.

Body

application/json

Strict v3 survey creation document. This endpoint accepts survey structure only: name, metadata, languages and language settings, welcome card, blocks/elements/logic, endings, hidden fields, variables, and rules before the first question (startLogic). App surveys (type: app) additionally accept the distribution (display options + triggers) and targeting (contact segment filters) objects; these are rejected for link surveys. It rejects legacy questions and out-of-scope settings such as styling, follow-ups, recaptcha, single-use/email verification, slug, custom scripts, analytics fields, timestamps, and createdBy.

Translatable fields use real locale-code maps. The map must include the canonical defaultLanguage key, such as en-US, so the server can persist the internal default translation. Locale keys must be canonical BCP 47 codes such as de-DE, pt-PT, or zh-Hans-CN. Non-default locale keys must be declared in languages; undeclared locale keys in metadata, welcome cards, blocks, or endings are rejected with unsupported_locale.

blocks[].id and variables[].id may be omitted on create and will be generated by the server. Provide explicit cuid2 ids when other fields in the same request reference them. For normal sequential flow, omit logicFallback. It is only valid together with a non-empty logic array on the same block.

workspaceId
string<cuid2>
required

Workspace where the survey will be created. Requires read/write access.

name
string
required
Minimum string length: 1
blocks
object[]
required
Required array length: 1 - 1000 elements
type
enum<string>
default:link

Survey type. link surveys are distributed by URL; app surveys are shown in-app and configure their runtime behavior via the distribution and targeting objects. type is immutable after creation (it cannot be changed via PATCH).

Available options:
link,
app
status
enum<string>
default:draft
Available options:
draft,
inProgress,
paused,
completed
metadata
object

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.

defaultLanguage
string
default:en-US

Default authoring locale. Translatable maps must include this locale key.

Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?-[A-Z]{2}$
Example:

"en-US"

languages
object[]

Optional survey language configuration. Every non-default locale used by translatable maps must be declared here; omitted languages are not inferred from map keys.

Maximum array length: 50
showLanguageSwitch
boolean | null

Show respondents a language switch on multi-language surveys. null and false both mean off.

autoSelectLanguage
boolean | null

Open link and app surveys in the respondent's browser language when it matches an enabled survey language; otherwise the default language is used. null and false both mean off.

welcomeCard
object

Optional card shown before the first survey block.

endings
object[]
Maximum array length: 100

Ending reached after the last block or a jump action. type selects the allowed shape; unsupported fields are rejected instead of ignored.

hiddenFields
object

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.

variables
object[]
Maximum array length: 100

Survey variable accepted by POST /api/v3/surveys. id may be omitted and will be generated by the server. Provide an explicit cuid2 id when logic in the same request needs to reference this variable.

startLogic
object[]

Rules before the first question. The survey runs them as soon as it loads, before the welcome card, and also when a start-at link skips ahead. Each rule has the block-rule shape (id, conditions, actions), but only three actions are allowed: jumpToBlock, to a block or to an ending (an ending is a screen-out: the respondent sees only that ending, and a finished response is stored that counts as Completed), calculate, to set a computed field, and markLowQuality, which marks the response Low quality with its first write (a screen-out's finished response included). requireAnswer and any other action are rejected with a 422 naming startLogic.<rule>.actions.<action>. Nothing has been answered yet, so conditions and values may read hiddenField (URL parameters), variable and reserved operands only; an element operand is rejected with a 422 naming startLogic.<rule>.conditions (or the action's value). A jump to a block or ending that does not exist is a dangling_reference. The first jump wins, every calculate runs, and with no jump the respondent continues to the first block (or the start-at target). [] means the survey has none.

Maximum array length: 100
Example:
embeddedFields
object[]

Typed Embedded Data (ADR 0028): the survey's complete set of computed and ingested fields, including workspace library fields linked by key. Optional: existing clients keep sending variables and hiddenFields alone, which work exactly as before. Sent alone, the legacy fields are derived from this list. Sent together with either legacy field, both have to describe the same fields — matched by storage key, comparing a variable's name, type and value — or the request is refused with 400, invalid_params naming each path where they differ. On create, an empty variables or hiddenFields counts as not sent.

Maximum array length: 300
distribution
object

App-survey runtime/display settings. Only valid when type is app.

Example:
targeting
object

App-survey contact targeting. Only valid when type is app.

customCss
object | null

Optional survey custom CSS source. Processed by the server; constructs it removes come back as top-level warnings on the 201. Adding CSS needs the Scale plan on Formbricks Cloud (403 custom_css_plan_required); CSS that cannot be processed is a 422 with details.errors. Processing counts against the custom CSS budget of 60 per minute per user or API key, shared with custom CSS validation; beyond it the create is a 429 and nothing is written.

Response

Survey created successfully

data
object
required

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

warnings
object[]

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.

Maximum array length: 50