Most research surveys should use built-in question settings. Custom code is for advanced instruments that need presentation, validation, or variables beyond standard configuration. Use it sparingly and test thoroughly before publishing.

Before adding code, check whether the same result can be handled with validation rules, Flow, condition assignment, or a standard question type. Custom code should have a clear owner and a clear reason.

1. Step 1: Open the survey editor. From Surveys, open the draft that needs advanced behavior.

   Step 1: Open the survey editor

   Personal Dashboard

   Live dashboard surface from the app shell (ephemeral help scene).

   Surveys

   New surveyImport

   Untitled surveyLast Modified

   Policy attitudes pilotLast Modified

2. Step 2: Start in Block Builder. Add or select the question where the custom HTML, JavaScript, or validation belongs.

   Step 2: Start in Block Builder

   Survey Editor

   No-persist demo using the real builder shell.

   Add a Block

   Add BlockPull Blocks

   Trash0 items

   Trash is empty.

3. Step 3: Use Flow only for routing logic. Open Flow when a custom variable should assign respondents to a condition arm or branch.

   Step 3: Use Flow only for routing logic

   Block Builder

   Flow

   Preview

   Deploy

   Export

   Flow Canvas

   Interactive routing surface from the app, running in no-persist help mode.

   Consent and Study Intro

   1 question

   Political Knowledge Block

   2 questions

   Control Message

   1 question

   Treatment Message

   1 question

   Outcome Measures

   2 questions

   Survey Ends

   Anchors explicit end of survey

4. Step 4: Verify in Preview and Export. Use Preview to test behavior, then submit a test response and review the exported values.

   Step 4: Verify in Preview and Export

   Block Builder

   Flow

   Preview

   Deploy

   Export

   Preview

   Walk through respondent-facing behavior in the same preview surface.

• Custom HTML: add specialized participant-facing markup when a normal prompt is not enough.
• Custom JavaScript: declare variables that can support advanced survey behavior or exports.
• Python validation: validate Short Answer responses with custom server-side logic.
• Python assignment rules: support advanced by-variable matching for condition arms.

• Start with built-in settings: use custom code only when standard question settings do not meet the protocol.
• Keep the scope small: make the code short, documented, and easy for collaborators to review.
• Preview dependent paths: test every path that depends on custom variables, validation, or assignment rules.
• Inspect exports: submit test responses and confirm custom values appear in the fields your analysis expects.
• Protect secrets: do not store API keys, tokens, or private credentials in participant-facing survey configuration.

Custom code can make a survey harder for collaborators to audit. Document why it exists, what variables it creates, how it fails, and how it affects respondent flow or data exports.

• Failure path: decide what respondents see if validation or assignment code rejects an answer.
• Versioning: record code changes before pushing them to a published survey.
• Review: ask a collaborator to read any code that affects eligibility, incentives, assignment, or primary outcomes.
• Export audit: keep a test response that proves the custom value appears where analysis expects it.

• Short Answer Survey Questions
• Create Experimental Conditions
• Survey Variable Names and Recodes
• Survey Data Quality Checks