Survey definition

A survey definition is a JSON document. The dashboard editor, the REST API, the MCP server and Kai all read and write this format, and Gleap validates it the same way everywhere.

{
  "schemaVersion": 2,
  "format": "card",
  "defaultLanguage": "en",
  "welcome": { … },
  "blocks": [ … ],
  "endings": [ … ],
  "fields": [ … ],
  "showProgress": true,
  "allowSkipBack": true
}

Top level

Always 2.

'card' | 'full'

required

card (compact card, bottom sheet on phones) or full (Typeform-style full screen). The legacy values survey and survey_full are deprecated aliases of card and full.

string

required

Locale of the default texts, for example en.

Welcome

Optional welcome screen before the first question — see Welcome screen.

Block[]

required

The questions in display order. 1–60 blocks.

Ending[]

required

Thank-you screens. 1–10 endings.

HiddenField[]

Hidden fields: values passed in by the SDK, URL parameters or personal links.

boolean

Show the progress bar.

boolean

Full screen: allow going back to earlier questions.

Theme

The survey’s design — see Theme. Every field is optional; unset fields use your widget settings.

object

{ userId? } — the teammate shown in the card’s sender row. Defaults to the project’s default sender.

Localized texts

Every text (title, description, choice label, …) is a map of locale to text:

{ "en": "How likely are you to recommend us?", "de": "Wie wahrscheinlich ist es, dass Sie uns weiterempfehlen?" }

Titles may contain tokens that are replaced for each respondent: {{contact.first_name}}, {{field.<hidden field key>}} and {{answer.<earlier answer key>}}.

Theme

theme sets the survey’s design. Every field is optional: a field you leave out uses your project’s widget settings (widget colour, widget logo, widget light/dark setting), so a survey without theme looks like your widget.

hex

Buttons, selected choices and the progress bar. Default: the widget colour.

hex

Text on brand-filled buttons and selected choices. Default: black or white, whichever contrasts better with brandColor.

'auto' | 'light' | 'dark'

Light or dark surfaces. auto (default) follows the widget’s light/dark setting.

'tint' | 'plain' | 'color' | 'image'

The backdrop of the full-screen format and the survey page. tint (default) is a light tint of the brand colour, plain has no tint, color uses backgroundColor, image uses backgroundImage. The card and the bottom sheet always stay a solid light or dark surface.

hex

Backdrop colour for background: "color".

string

Backdrop image for background: "image". Must be an https URL without quotes, parentheses or whitespace.

number

0–0.8. Black darkening over a colour or image backdrop so text stays readable. Default 0.3 for images, 0 for colours.

hex

Text on the full-screen and survey page backdrop. Default: picked by contrast — light text on dark colours and images.

'sharp' | 'rounded' | 'pill'

Corner radius of choices, buttons and inputs. Default rounded.

string

https URL of the logo. Default: the widget logo.

boolean

Show the logo — top left in the full-screen format and in the survey page header. Default true.

Where each field applies:

	Card / bottom sheet	Full screen	Survey page
`brandColor`, `buttonTextColor`, `corners`, `appearance`	✓	✓	✓
`background`, `backgroundColor`, `backgroundImage`, `backgroundOverlay`, `textColor`	—	✓	✓
`logoUrl`, `showLogo`	—	✓	✓

A brand colour, a photo backdrop darkened for legibility and pill-shaped choices:

"theme": {
  "brandColor": "#0f766e",
  "background": "image",
  "backgroundImage": "https://cdn.example.com/surveys/forest.jpg",
  "backgroundOverlay": 0.4,
  "corners": "pill"
}

Colours are hex (#0f766e, #fff, or with alpha). An invalid backgroundImage or backgroundColor falls back to tint.

Resolved theme

The SDK and the survey page load a survey through GET /surveys/{id} and GET /surveys/page/{slug}. Both return theme with the widget defaults already filled in:

"theme": {
  "brandColor": "#0f766e",
  "appearance": "auto",
  "autoAppearance": "system",
  "background": "image",
  "backgroundImage": "https://cdn.example.com/surveys/forest.jpg",
  "backgroundOverlay": 0.4,
  "corners": "pill",
  "showLogo": true,
  "logoUrl": "https://cdn.example.com/logo.png",
  "widgetBackgroundColor": "#ffffff",
  "buttonColor": "#0f766e",
  "defaults": { "brandColor": "#485bff", "appearance": "system", "logoUrl": "https://cdn.example.com/logo.png", "backgroundColor": "#ffffff" }
}

Field
`brandColor`, `background`, `backgroundOverlay`, `corners`, `showLogo`, `appearance`	Always present, defaults applied.
`autoAppearance`	What `auto` means for this project: `light`, `dark` or `system` (follows the visitor’s device).
`buttonTextColor`, `textColor`	Only when the survey sets them; otherwise pick by contrast.
`backgroundColor`, `backgroundImage`	Only for a `color` / `image` background.
`logoUrl`	The survey logo, else the widget logo; absent when `showLogo` is `false` or there is no logo.
`widgetBackgroundColor`, `buttonColor`	The widget’s own colours, when set.
`defaults`	The widget values unset fields fall back to: `brandColor`, `appearance`, `logoUrl?`, `backgroundColor?`.

Blocks

string

required

Stable id, unique across blocks and endings (letters, digits, _, -; max 40). Jumps point to it.

string

required

Stable answer key, unique, ^[a-z][a-z0-9_]{1,40}$ — for example nps_score. Webhooks, exports, the API and filters use it. Don’t rename it on a live survey.

string

required

One of the types below.

Localized

required

The question.

Localized

Help text under the question.

boolean

required

Whether the question must be answered. statement blocks are never required; a required consent must be ticked.

string | number | boolean | string[]

Preselected answer the question starts with: a choice id (single), choice ids (multi), a scale value, true / false (yesno) or text. The respondent still confirms it; nothing is saved before. Must be a valid answer of the block (invalid_default otherwise).

Jump[]

required

Logic rules, checked top to bottom; the first match wins. Max 20. [] for none.

string | null

required

”All other cases go to”: a later block id or an ending id. null = the next block in order (after the last block, the first ending).

Type-specific options:

Type	Answer value	Options
`nps`	number 0–10	`scaleStyle` (`numbers` / `emoji` / `compact`), `lowLabel`, `highLabel`. `compact` shows six buttons 0–5 that answer 0, 2, 4, 6, 8, 10, so NPS groups and logic stay on 0–10 (the pre-2.0 “modern” NPS)
`csat`	number 1–5	`scaleStyle`
`rating`	number `scaleMin`–`scaleMax`	`scaleMin`, `scaleMax`, `scaleStyle` (`stars`)
`scale`	number `scaleMin`–`scaleMax`	`scaleMin`, `scaleMax`, `scaleStyle`, `lowLabel`, `highLabel`
`single`	choice id, or `{ "other": "…" }`	`choices` (max 25), `allowOther`, `randomize`
`multi`	array of choice ids (plus `{ "other": "…" }`)	`choices`, `allowOther`, `randomize`, `minSelect`, `maxSelect`
`yesno`	`true` / `false`	—
`short`, `long`	string	`placeholder`, `maxLength`
`email`	string	`placeholder`
`number`	number	`placeholder`
`date`	`YYYY-MM-DD`	—
`upload`	array of file URLs	`accept` (file types like an `<input accept>`: `.png,.jpg,application/pdf`, `image/*`)
`statement`	— (no answer)	—
`consent`	`true` (ticked)	`linkUrl` (https, the policy), `linkLabel` (its text, default “privacy policy”). `title` is the checkbox text; leave it empty to show the widget’s “I have read and accept the privacy policy.” in the respondent’s language. Logic only on `answered` / `skipped`

Choices are { "id": "too_expensive", "label": { "en": "Too expensive" } }. Choice ids are unique within the block; answers and conditions use the id, never the label. Any block can also carry media: { type: 'image' | 'video', url }.

Logic: jumps and conditions

A jump is { "if": <condition>, "go": "<block id or ending id>" }. go must point to a later block or to an ending — jumps never go backwards, so there are no loops. Where a person goes after answering:

the first jump whose condition matches,
otherwise next,
otherwise the next block in order,
after the last block, the first ending.

Conditions on the answer

Condition	Use with
`{ "src": "answer", "op": "eq", "value": "too_expensive" }`	`single` (choice id), `yesno` (`true`/`false`), numbers
`{ "src": "answer", "op": "neq", "value": … }`	same as `eq`
`{ "src": "answer", "op": "between", "value": [0, 6] }`	`nps`, `csat`, `rating`, `scale`, `number` — inclusive
`{ "src": "answer", "op": "includes", "value": "slack" }`	`multi` (choice id)
`{ "src": "answer", "op": "answered" }` / `"skipped"`	any optional question

Conditions on the person

Condition	Meaning
`{ "src": "contact", "key": "plan", "op": "eq", "value": "pro" }`	Contact property. `op`: `eq`, `neq`, `contains`, `exists`.
`{ "src": "field", "key": "source", "op": "eq", "value": "newsletter" }`	Hidden field (must be listed in `fields`).
`{ "src": "url", "op": "contains", "value": "/billing" }`	Page URL the survey is shown on. `op`: `contains`, `eq`.

The editor lists person conditions before answer conditions; put them first when you write definitions yourself.

Welcome screen

welcome adds an intro screen before the first question, like Typeform’s. It is not a block: it has no answer key, no logic and does not count as a question. In full screen and on the survey page it shows centred, with the optional image, a large title, the description, the Start button (“press Enter ↵”) and the time estimate. The card and the phone bottom sheet show a compact version (title, description, Start). People who come back to finish a response they started skip it.

boolean

required

true shows the welcome screen. false keeps the texts without showing them.

Localized

required

The heading. Required when enabled is true; may contain tokens like {{contact.first_name}}.

Localized

One or two sentences under the title.

Localized

Start button text. Default “Start”.

object

{ type: "image", url } — an image above the title (full screen and survey page). https only.

boolean

Show “Takes about N minutes” (about 15 seconds per question). Default true.

"welcome": {
  "enabled": true,
  "title": { "en": "Help shape Acme" },
  "description": { "en": "Three quick questions. Your answers go straight to the product team." },
  "buttonLabel": { "en": "Let's go" },
  "media": { "type": "image", "url": "https://cdn.acme.com/survey-hero.png" }
}

Use the welcome screen rather than a leading statement block: question numbers, the step funnel and “starts” (first answer) stay the same, and the analytics report how many people pressed Start.

Endings

string

required

Unique across blocks and endings.

Localized

required

Thank-you text.

Localized

object

{ label: Localized, url } — a call to action.

string

Survey page: redirect after this ending.

number

In the app: close after N seconds.

string

Tag added to the contact who reaches this ending.

Hidden fields

"fields": [{ "key": "plan", "label": "Plan" }, { "key": "source" }]

Values come from showSurvey(id, { fields }), URL parameters on the survey page (?plan=pro) and personal links. They are stored on the response under fields.

Validation

Gleap rejects a definition at publish time when:

ids or keys are missing, malformed or duplicated (ids are unique across blocks and endings; choice ids within a block),
a go or next points to an unknown id or to an earlier block (loop),
a block can’t be reached from the first block, or a path doesn’t end in an ending,
a condition doesn’t fit its block type (for example includes on a single block, between: [0, 11] on NPS, or a value condition on a consent),
scaleStyle: 'compact' is set on anything but NPS, or a defaultValue is not a valid answer of its block,
a limit is exceeded: 60 blocks, 10 endings, 25 choices per block, 20 jumps per block.

Saving a draft accepts invalid logic and returns the problems as warnings; publishing returns 422 with the same list. Use POST /validate to check a definition without saving. Errors look like:

{ "ok": false, "errors": [{ "path": "blocks.2.jumps.0.go", "code": "backward_jump", "message": "\"q_reason\" is not after this block" }] }

Example: NPS with follow-ups

Detractors (0–6), passives (7–8) and promoters (9–10) each get their own follow-up question.

{
  "schemaVersion": 2,
  "format": "card",
  "defaultLanguage": "en",
  "blocks": [
    {
      "id": "q_nps", "key": "nps_score", "type": "nps", "required": true,
      "title": { "en": "How likely are you to recommend us to a friend?" },
      "lowLabel": { "en": "Not likely" }, "highLabel": { "en": "Very likely" },
      "jumps": [
        { "if": { "src": "answer", "op": "between", "value": [0, 6] }, "go": "q_detractor" },
        { "if": { "src": "answer", "op": "between", "value": [7, 8] }, "go": "q_passive" },
        { "if": { "src": "answer", "op": "between", "value": [9, 10] }, "go": "q_promoter" }
      ],
      "next": null
    },
    { "id": "q_detractor", "key": "detractor_reason", "type": "long", "required": false,
      "title": { "en": "Sorry to hear that. What disappointed you?" }, "jumps": [], "next": "end_thanks" },
    { "id": "q_passive", "key": "passive_improve", "type": "long", "required": false,
      "title": { "en": "What would make it a 10?" }, "jumps": [], "next": "end_thanks" },
    { "id": "q_promoter", "key": "promoter_love", "type": "long", "required": false,
      "title": { "en": "Great! What do you love most?" }, "jumps": [], "next": "end_thanks" }
  ],
  "endings": [{ "id": "end_thanks", "title": { "en": "Thanks for your feedback!" } }],
  "fields": [],
  "showProgress": true,
  "allowSkipBack": true
}

Example: cancellation survey

People who pick “Too expensive” are asked what price would have worked; everyone else goes straight to “What could we have done better?”. People who agree to be contacted are tagged.

{
  "schemaVersion": 2,
  "format": "full",
  "defaultLanguage": "en",
  "blocks": [
    {
      "id": "q_reason", "key": "cancel_reason", "type": "single", "required": true,
      "title": { "en": "What's the main reason you're leaving?" },
      "choices": [
        { "id": "too_expensive", "label": { "en": "Too expensive" } },
        { "id": "missing_features", "label": { "en": "Missing features" } },
        { "id": "switching", "label": { "en": "Switching to another tool" } },
        { "id": "not_using", "label": { "en": "Not using it enough" } }
      ],
      "allowOther": true,
      "jumps": [{ "if": { "src": "answer", "op": "eq", "value": "too_expensive" }, "go": "q_price" }],
      "next": "q_better"
    },
    { "id": "q_price", "key": "fair_price", "type": "number", "required": false,
      "title": { "en": "What monthly price would have worked for you?" }, "jumps": [], "next": "q_contact" },
    { "id": "q_better", "key": "do_better", "type": "long", "required": false,
      "title": { "en": "What could we have done better?" }, "jumps": [], "next": null },
    {
      "id": "q_contact", "key": "may_contact", "type": "yesno", "required": true,
      "title": { "en": "May we contact you about this, {{contact.first_name}}?" },
      "jumps": [{ "if": { "src": "answer", "op": "eq", "value": true }, "go": "end_contact" }],
      "next": "end_bye"
    }
  ],
  "endings": [
    { "id": "end_contact", "title": { "en": "Thanks — we'll be in touch." }, "tagContact": "churn-followup" },
    { "id": "end_bye", "title": { "en": "Thanks for being a customer." } }
  ],
  "fields": [],
  "showProgress": true,
  "allowSkipBack": true
}

Responses

Answers are stored keyed by the block’s key:

{
  "id": "rsp_4kq9X2mT7vB1nR8sLp3Z",
  "surveyId": "q7x2kd",
  "version": 3,
  "status": "completed",
  "answers": { "cancel_reason": "too_expensive", "fair_price": 49, "may_contact": true },
  "path": ["q_reason", "q_price", "q_contact", "end_contact"],
  "endingId": "end_contact",
  "channel": "web",
  "fields": { "plan": "pro" },
  "language": "en",
  "startedAt": "2026-10-06T09:12:03.000Z",
  "completedAt": "2026-10-06T09:12:41.000Z"
}

channel is one of web, ios, android, page, email, embed, conversation, api.

Get Started

SDKs

Kai Code

Surveys

Server-side event tracking

Guides

Top level

Localized texts

Theme

Resolved theme

Blocks

Logic: jumps and conditions

Conditions on the answer

Conditions on the person

Welcome screen

Endings

Hidden fields

Validation

Example: NPS with follow-ups

Example: cancellation survey

Responses

​Top level

​Localized texts

​Theme

​Resolved theme

​Blocks

​Logic: jumps and conditions

​Conditions on the answer

​Conditions on the person

​Welcome screen

​Endings

​Hidden fields

​Validation

​Example: NPS with follow-ups

​Example: cancellation survey

​Responses

Top level

Localized texts

Theme

Resolved theme

Blocks

Logic: jumps and conditions

Conditions on the answer

Conditions on the person

Welcome screen

Endings

Hidden fields

Validation

Example: NPS with follow-ups

Example: cancellation survey

Responses