Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.smartinterview.ai/llms.txt

Use this file to discover all available pages before exploring further.

Welcome! This tutorial walks you through everything you need to ship your first questionnaire in Smartinterview: building it, testing it, reviewing the answers, and exporting the raw data.

​
1. Create a new survey

A hands-on, end-to-end walkthrough of the Smartinterview builder. By the end of this document, you will know how to:
  • Create a survey from scratch or import one from an existing PDF / DOCX
  • Design every type of question the platform supports
  • Add AI-driven conversational (smartquestion) blocks with follow-ups
  • Localise question text and navigation buttons into any of 10 languages
  • Configure display conditions and URL variables
  • Test the survey in three different ways before sharing it
  • Generate synthetic test data
  • Visualise responses in the Data tab
  • Export raw data to Excel, CSV, or JSON
  • Deploy and share the survey (direct link or embedded iframe)

​
1. Creating a survey

From the dashboard, click + New survey. You are dropped into the builder with:
  • An empty questions list
  • A default End Screen already wired at the bottom
  • The “No created questions yet” empty state in the centre panel, showing two buttons: + Create question and Import a file

​
1a. Create questions from scratch

  1. Click + Create question.
  2. A new question appears in the list (named Q1) and the editor opens.
  3. Type the question title directly in the centre canvas.
  4. Click + Create question.
  5. A new question appears in the list (named Q1) and the editor opens.
  6. Type the question title directly in the centre canvas.

​
1b. Import an existing questionnaire (PDF / DOCX)

If you already have a questionnaire written, you do not need to re-type it.
  1. Click Import a file in the empty state (or + Add question then “Import” if you already have other questions).
  2. Drag-and-drop or choose a .pdf or .docx file (max 25 MB).
  3. Click Importer and wait for the “Importation en cours…” toast.
  4. When the import finishes, every question the LLM detected appears in the builder with the right type already selected:
    Detected typeWhat you get
    radioRadio Group with the choices from the source
    dropdownDropdown
    checkbox_groupCheckbox Group
    booleanYes/No checkbox
    numberNumber input
    scaleSlider with the detected min / max
    likertCheckbox Table with Likert columns
    long_text or vocalsmartquestion (AI voice + follow-ups)
    textShort text
  5. Skip-logic conditions and min/max ranges are preserved when they’re explicitly stated in the source document.
Tip: the import uses AI. For complicated layouts it’s worth opening each question afterwards and verifying both the title and the control type match what you expected.

​
2. The builder at a glance

Builder interface Once you create a survey you land on the builder. The interface has three main regions:
  • Header — a single Settings toggle on the left and a four-button segmented toggle for the builder modes. Deploy opens a pop-up with the shareable links; it is not a tab.
  • Center panel — everything you design or preview for the currently selected question. Its content changes with the mode selected in the header.
  • Right panel — the question list, the controls palette (expert mode only), and the Endings list (welcome/end screens).
  • When you click Data, the Questions panel auto-collapses to give the response table room to breathe.

​
3. Writing the question title

Click anywhere in the large title area and start typing. Smartinterview uses a Notion-like WYSIWYG editor with a floating bubble toolbar that appears when you select text: Click anywhere in the large title area and start typing. Smartinterview uses a Notion-like WYSIWYG editor with a floating bubble toolbar that appears when you select text:
ButtonWhat it does
H1 / H2 / H3Headings (for long multi-line questions)
B / I / SBold, italic, strikethrough
TFont family + size
🎨Text colour
≡Alignment (left / centre / right)
🖼Insert image
🌐Translate (see section 4)
The editor accepts inline images (drag-and-drop or paste a URL) and supports keyboard shortcuts for bold/italic/underline (⌘B, ⌘I, ⌘U).

​
4. Translating a question (10 languages)

Smartinterview stores a primary language per question and any number of translations alongside it. Smartinterview stores a primary language per question and any number of translations alongside it.
  1. Write the question in whatever language feels most natural — this becomes the primary language.
  2. Select any portion of the question title so the bubble toolbar appears.
  3. Click the 🌐 icon on the far right of the toolbar.
  4. A hover menu lists every supported language:
    • Français (FR) ★ principale
    • English (EN)
    • Deutsch (DE)
    • Español (ES)
    • العربية (AR)
    • हिन्दी (HI)
    • Português (PT)
    • Português (BR)
    • ไทย (TH)
    • 中文 (ZH)
    • 日本語 (JA)
    • Français (FR) ★ principale
    • English (EN)
    • Deutsch (DE)
    • Español (ES)
    • العربية (AR)
    • हिन्दी (HI)
    • Português (PT)
    • Português (BR)
    • ไทย (TH)
    • 中文 (ZH)
    • 日本語 (JA)
  5. Click the target language. Smartinterview calls the translation API and writes the result to uischema.options.translations[<lang>].
  6. The editor view automatically switches to the newly-translated version so you can verify and fine-tune it inline.
  7. Click the 🌐 icon again and pick ★ principale to go back to the original — no second API call.
  8. Click the target language. Smartinterview calls the translation API and writes the result to uischema.options.translations[<lang>].
  9. The editor view automatically switches to the newly-translated version so you can verify and fine-tune it inline.
  10. Click the 🌐 icon again and pick ★ principale to go back to the original — no second API call.
Respondents see the version that matches their URL locale (/fr/…, /en/…, /de/…, etc). If a translation isn’t set for their locale, they fall back to the primary language.

​
5. Adding answer blocks

Every question can contain one or more answer blocks. In expert mode the full palette is visible on the right. In simple mode only the most common blocks are shown to keep the UI approachable.

​
5a. The full block catalogue

GroupBlockUse it when
Yes / NoCheckboxSingle yes/no or opt-in
ToggleYes/no but in switch form
ChoicesRadio GroupSingle choice from a short list
DropdownSingle choice from a long list
Checkbox GroupMulti-select from a short list
Checkbox TableMatrix: multi-select across rows × columns (Likert scales etc.)
Open Text TableMatrix: free text in each row × column cell
TextShort TextOne-line free text
NumberNumberNumeric value
SliderScale / NPS (0-10, 1-5, etc.)
AIsmartquestionConversational AI-powered interview with follow-ups
SpecialWelcome ScreenFirst-screen landing with a Start button
End ScreenThank-you screen
RedirectRedirectionAuto-redirect to another URL

​
5b. Adding a block

  1. Pick a question in the right-hand list.
  2. Click any block in the Controls palette. It’s inserted at the bottom of the current question.
  3. Hover over the new block — a toolbar appears on the top-right corner with a pencil (edit) and a trash (delete) icon.
  4. Click the pencil to open the edit popover where you can:
    • Change the block type (within the same group)
    • Rename the label
    • Toggle Required
    • See the internal response ID (e.g. ctrl1)
  5. Click the trash to delete the block.

​
5c. Matrix blocks (Checkbox Table & Open Text Table)

Both matrix blocks open with a default 2 rows × 3 columns grid and an inline editor bar: 
[+ Row] [+ Column]   [R: Row 1 ×]  [R: Row 2 ×]   [C: Column 1 ×]  [C: Column 2 ×]  [C: Column 3 ×]
  • + Row / + Column — grow the matrix. New rows get a fresh property key on the schema so answers stay separated.
  • R:/C: chips — click any chip to rename the row or column inline. Hit Enter to commit, Escape to revert.
  • × on hover — delete a row or column (the last one is protected so the matrix is never empty).
Checkbox cells behave like a multi-select per row. Text cells accept free text at every intersection.

​
5d. Smartquestion (AI conversational block)

Adding a smartquestion converts the question into an AI-driven interview. Respondents see:
  • A large circular microphone button in the middle of the screen
  • A small “I prefer to write” checkbox under it
They can either speak (click the mic, talk, click again to stop; the platform transcribes on the fly) or type (toggle the checkbox and a text box appears). Either way, the AI then generates follow-up questions — the full Q/R chain is stored on the answer. As soon as you select a question that contains a smartquestion, an AI config panel slides in on the right with these fields:
  • Question — the visible prompt (mirrors the question title)
  • Contexte — the persona / instructions passed to the AI (e.g. “You are a market research specialist investigating brand perception…”). This is what steers the follow-ups.
  • Mode — optional tags (Vérification noms propres, Relances AI)
  • Mode de réponse
    • Vocale — voice only
    • Vocale ou texte — voice with a “I prefer to write” fallback (default)
    • Texte — text only
    • Vidéo — video recording
  • Relances — number of AI follow-ups, 1 to 4 (default 2)
  • Langue — the interview language, or None (user locale) to auto-match
In expert mode, the inline smartquestion card collapses to a simple mic-only visual so you don’t see the same config twice — the side panel is the source of truth.

​
6. Editing navigation buttons (Next / Previous)

Below every question preview, the builder shows a Next Question button (and a Previous button when the question is not the first in the order). Both labels are click-to-edit:
  1. Click directly on the label.
  2. Type your replacement text.
  3. Hit Enter to commit (or click outside). Escape cancels.
Labels are saved per question under uischema.options.navigation.{nextLabel, previousLabel} and respondents see them exactly as written. If you leave a label empty it falls back to the locale-wide default (Next Question in English, Question suivante in French, etc.).

​
7. Display conditions (skip logic)

Click Conditions at the bottom of the right panel to configure when a question is shown. You can chain rules like: 
Show this question WHEN
  Q1.ctrl1 == "choice1"
  AND Q2.ctrl1 > 5
Conditions reference earlier questions by their response ID and support the comparison operators ==, !=, >, <, >=, <=. Imported questionnaires preserve any conditions the original document expressed.

​
8. Paramètres tab

Click Paramètres in the header to jump to survey-level settings:

​
8a. Variables URL

Define named variables that can be passed via the survey URL (?gender=F&age=25) and referenced in display conditions or the End Screen return URL template. Each variable has a name, a type (text, number, boolean, object), and an optional default value.

​
8b. Expert features

A single toggle that enables the full expert palette, the expert smartquestion editor, and the Preview / Widget tabs. Keep it off for authors who only need the simple-mode blocks.

​
9. Testing the survey

There are three complementary ways to QA a survey before sharing it.

​
9a. Test mode (inside the builder)

Click the Test button in the header’s mode toggle. The currently selected question renders exactly as a respondent sees it, with a working Next Question button that navigates the whole flow. The end screen, the welcome screen, and any smartquestion follow-ups all fire normally. Test mode is perfect for checking styling, slider defaults, matrix layouts, and the mic interaction without any network latency. Click Deploy in the header. A small pop-up lists one direct link per supported locale: Deploy screen 
FR   https://www.smartinterview.ch/fr/<survey-id>
EN   https://www.smartinterview.ch/en/<survey-id>
DE   https://www.smartinterview.ch/de/<survey-id>
Toggle Mode test on at the top of the dialog and each link is augmented with ?user_id=test_<random>. Because each test_<random> is treated as a brand-new respondent, you can:
  • Take the same survey multiple times from the same browser
  • Skip the “already completed” end-screen cache that real respondents would see on a repeat visit
  • Separate QA answers from real ones later (all user_id values starting with test_ are still written to the database but are easy to filter out)
Every time you toggle Mode test on, a fresh user_id is generated — copy the link, take the survey, toggle off and back on for the next run.
Warning: a link without ?user_id= remembers completion in localStorage. If you take a real link twice in the same browser the second visit lands directly on the end screen. Always use Mode test during QA.

​
9c. Generating synthetic test data

Once you have a test link, 2–3 runs is usually enough to light up every question in the Data tab:
  1. Open the link in an Incognito / Private window to avoid cookie bleed.
  2. Fill only the required fields (red asterisk). Optional fields can be skipped.
  3. On smartquestion blocks, type a short answer so the AI has something to follow up on. Two or three sentences produce a realistic Q/R thread.
  4. For each synthetic respondent, flip Mode test off and on in the Deploy dialog so you get a new user_id, then copy the updated link.

​
10. Reviewing responses (Data tab)

Click Data in the header. The Questions panel collapses and the centre fills with a pivoted table: Dataset
  • One row per unique user_id.
  • One column per non-special question, in builder order.
  • — marks a question the respondent didn’t reach or didn’t answer.
  • The first two columns (# + Respondent) are sticky-left, so they stay pinned while you scroll horizontally through many questions.

​
10a. Filtering

Above the table, a chip bar lets you narrow the view: 
Filtrer par question :  [All (N)] [Q1 (n)] [Q2 (n)] [Q3 (n)] …
  • All — show every question (default). The number is the respondent count.
  • Qx — show only that one column. Other columns are hidden, rows remain.

​
10b. AI / smartquestion cells

For conversational questions, the cell renders the full Q/R conversation stacked inline: 
R: I was looking for better pricing.
Q: Can you clarify what you mean by "better"?
R: The competition is 20% cheaper.
Q: What features matter most to you?
R: Speed and reliability.
Original follow-up questions are in italic grey (marked Q:). Respondent answers are in solid text (marked R:).

​
10c. Personas

Personas

​
The Generate personas button creates scenarios to help anticipate the launch of an AI survey. Click the Save icon to store them so they appear in the dataset.

​
11. Exporting raw data

At the top-right of the Data tab, click Télécharger / Download for a dropdown of export formats:
FormatWhat you get
Excel (.xlsx)A multi-sheet workbook. One sheet lists every respondent with their answers, one sheet per question if you need to dig.
CSVA flat file with one row per respondent. Multi-value fields are pipe-joined. Opens cleanly in pandas / R / Stata.
JSONThe raw answer blobs exactly as stored in the database. The most lossless format — use it if you’re building an integration.
Under the hood, the button calls: 
GET /api/survey/<survey-id>/export?format=excel|csv|json
Only the survey owner (or a member of the owning company) can call it, so your data is not publicly reachable. For programmatic access to responses per question, there’s also: 
GET /api/survey/<survey-id>/answers?question_id=<question-id>
/ which returns structured Q/R parts. This is exactly what the Data tab reads internally, so it’s handy when you want to debug what the platform sees for a specific submission.

​
12. Deploying & sharing

Once the survey is ready for real respondents:
  1. Make sure every question has a meaningful title (and translations if your audience is multilingual).
  2. Click Deploy in the header.
  3. Copy the link for the locale you want to share. Note that the link starts with the locale path segment (/fr/, /en/, /de/) — the survey UI (Next button text, end screen strings, error messages) auto-localises based on that segment.
  4. Share the link on your own channel (email, panel provider, QR code, Slack…).
  5. Optionally append tracking parameters: 
    https://www.smartinterview.ch/en/<survey-id>?gender=F&age=25&source=linkedin
    Any parameter declared under Paramètres → Variables URL becomes available inside display conditions and the End Screen return URL template.

​
Embedding in your own site (expert mode)

If you prefer to host the survey inside your own site:
  1. Enable expert mode in Paramètres → Expert features.
  2. Switch to the Widget tab that appears.
  3. Customise width, height, and theme.
  4. Copy the generated <iframe> snippet and paste it into your site.
  5. The iframe posts a smartinterview:complete message to the parent window when the respondent finishes — use it to trigger any follow-up logic on your side.

​
13. Sharing / collaboration

  • Invite teammates from the Inviter un membre button in the dashboard sidebar. Company members inherit RLS permissions and can edit every survey owned by the company.
  • All builder edits are auto-saved two seconds after the last change; the header displays Dernière sauvegarde : HH:mm so you always know the latest save time.

​
14. Troubleshooting cheat sheet

SymptomWhat to check
”Aucune réponse manquante” error on a slider I haven’t touchedThe slider auto-seeds its default value on mount. If you still see the error, hard-refresh the tab — the cache may be stale.
End screen appears immediately on a test linkYou visited the link previously without ?user_id=.... Either clear localStorage for that origin or copy a fresh Mode test link from the Deploy dialog.
Imported questions “disappear” after refreshThe questions are staged in the browser’s draft state. Wait two seconds for the auto-save indicator to turn green before refreshing.
Next button shows in the wrong languageSomeone set a per-question custom label that overrides the URL locale. Open each question in Edit mode and clear the Next / Previous button text.
Matrix has too many rows after testingDelete extra rows from the builder’s matrix editor (× on hover). At least one row and one column are preserved.
smartquestion doesn’t generate follow-upsCheck the AI config panel on the right: Contexte must be non-empty, and Relances must be ≥ 1.