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, welcome card, blocks/elements/logic, endings, hidden fields, and variables. 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
Minimum array length: 1
​
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.

​
welcomeCard
object

Optional card shown before the first survey block.

​
endings
object[]

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.

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[]

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.

​
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.

Response

Survey created successfully

​
data
object
required