QUESTIONSTAR

Creates a respondent in the survey's respondent list (the list 'External for {survey}' is auto-created, unknown custom fields are auto-created too). PersonalizedID is optional and NOT checked for uniqueness; when omitted, the respondent's links use the generated internal ID. sendInvitation: the invitation email is sent ONLY when explicitly true — leave it off unless the user clearly asked to send invitations. Returns the contact's PERSONAL survey link (surveyLink, …/Share/{code}/{personalizedID}); responses through it are attributed to this contact. Verified by readback: the respondent is read back after the write and the reply reports what is actually stored, not merely the acknowledgement of the write.

create_respondent

Creates a new empty survey (one page, no questions) and returns its 8-char code. Build it up with add_question, then publish_survey. The survey is owned by and visible to you; language defaults to de. Verified by readback: the new survey is read back through get_survey and the reply reports what actually exists under the new code. On failure nothing is left behind. The survey is created as an empty container; its questions, pages and logic are added by the authoring tools afterwards. survey_quality_guidelines returns QUESTIONSTAR's survey-design checklist.

create_survey

Records a response collected outside the survey link — e.g. a paper questionnaire, a phone or in-person interview, or an import from another system. Such responses are stored with source 'external' and can be told apart from responses submitted through the share link. Creates a new response (result case) in a survey. The survey's publication must be started. Answers go into Items: each item addresses a question by its variable name (Q1, Q2.3, Q<CustomID> — get them via get_survey) and carries the answer in Value. PersonalizedID is optional; if supplied and a response with it already exists, the call fails — use update_survey_response to modify. Technical data (host, user agent, device, dates) is set server-side and is not part of the input. Verified by readback: the response is re-read from the survey's stored data afterwards and the reply reports what is actually stored, not merely that the write was acknowledged. That read costs one heavy-class request, and it needs a PersonalizedID to address the response by.

create_survey_response

Creates a webhook: the survey's events are POSTed as JSON to your https URL from then on. Standing configuration with side effects — confirm with the user first: call WITHOUT confirm for a PREVIEW, then again with confirm:true. The preview creates no webhook, but sends one sample HTTPS POST to targetURL to check reachability — preview only against addresses you own or trust. Health grading: 2xx = healthy, 0 = unreachable, other codes = the endpoint refused the sample. An unreachable target (0) blocks creation unless force:true is passed; other non-2xx answers warn but create. eventType: ResponseRecieved (a response was submitted or updated — payload carries the answers) or SurveyPublished (the survey was (re)started). Personal/contact fields are NEVER sent — only question answers: includeFields accepts question variable names as returned by get_survey (Q1, Q3.2, …); left empty, it is expanded to the explicit list of ALL question variables, so contact columns stay out of the payload by construction. Verified by readback: the created hook is re-read from the survey's webhook list before success is reported. Fire a sample with test_webhook and watch health with get_webhook_deliveries.

create_webhook

Deletes a question from a survey. Collected answers are keyed to a stable internal code per question, so the data of the other questions is unaffected. What changes: (1) the deleted question's own answers are deleted with it; (2) the positional variable names Q{n} of every later question shift (Q5 becomes Q4, ...) — addressing only; get_survey returns the new names, and custom IDs keep a stable name across edits; (3) logic rules that reference the deleted question break; get_survey lists them in logic.errors until they are deleted or redefined (add_display_logic_rule / add_jump_logic_rule). Called without confirm the tool returns a preview with the response count, the dependent logic rules and the remaining question count and changes nothing; confirm:true performs the delete. The delete is verified server-side by re-reading the survey. Requires the edit-survey right.

delete_question

Deletes a page from a survey and returns the current page list (number, title, question count, flags). page is the 1-based number of the page to remove. If the page has questions you must pass moveQuestionsTo (another page number) or the delete is refused; the last page cannot be deleted. Page numbers are positional, so the pages after the removed one renumber. Verified by readback. Requires the edit-survey right on this survey.

delete_survey_page

Permanently deletes a response by PersonalizedID. Irreversible — for erroneous or test responses. Returns confirmation; deleting a non-existent response reports not-found, not an error, and an unknown survey code is reported as an unknown code — never as an absent response. Verified by readback: the response is re-read afterwards and the reply reports whether it is really gone.

delete_survey_response

Removes a webhook subscription — events stop being delivered to its URL immediately; irreversible (recreate with create_webhook if needed). Confirm with the user first: call WITHOUT confirm for a read-only PREVIEW, then again with confirm:true. The deletion is verified server-side: an unknown or already-deleted webhook is refused with 'Webhook not found.', so a success reply means a real subscription was removed.

delete_webhook

Exports the respondents pipeline report — one row per respondent across all respondent lists assigned to the survey's publication — as CSV, and returns a download link. The link is an unguessable URL with a 128-bit random token; it expires after ~15 minutes. Re-run for a fresh link; never returns inline file bytes. The file contains the contact data of the user's own contact lists for this survey: names, email addresses, custom fields and each contact's personal survey link. The link is temporary.

export_respondents_csv

Exports the respondents pipeline report — one row per respondent across all respondent lists assigned to the survey's publication — as SPSS (.sav), and returns a download link. The link is an unguessable URL with a 128-bit random token; it expires after ~15 minutes. Re-run for a fresh link; never returns inline file bytes. The file contains the contact data of the user's own contact lists for this survey: names, email addresses, custom fields and each contact's personal survey link. The link is temporary.

export_respondents_spss

Exports the respondents pipeline report — one row per respondent across all respondent lists assigned to the survey's publication — as XLSX, and returns a download link. The link is an unguessable URL with a 128-bit random token; it expires after ~15 minutes. Re-run for a fresh link; never returns inline file bytes. The file contains the contact data of the user's own contact lists for this survey: names, email addresses, custom fields and each contact's personal survey link. The link is temporary.

export_respondents_xlsx

Exports ALL responses of a survey as a downloadable file (variables as columns, one row per response) and returns a temporary download link — never inline file bytes. The link is an unguessable URL with a 128-bit random token; it expires after ~15 minutes. Re-run the tool for a fresh link. Besides the question columns the file carries the response's system columns, among them the respondent ID and the query-string parameters of the link the response came from. Returns a temporary file link, suited to large data sets; list_survey_responses returns the same data inline. Column names are Q-codes as returned by get_survey (or custom IDs with useCustomID). All timestamps are UTC. Counted against the export rate class (12 requests per hour per token). The SPSS/CSV/XLSX file can be used for analysis outside the built-in stat tools. Respondent contact / personal data is not returned through this API.

export_survey_responses

Returns the timestamp of the survey's most recent response; the minimum DateTimeOffset value when the survey has no responses yet.

get_last_response_time

Returns quota-disqualification statistics: Value = disqualified responses, Total = all responses.

get_quota_disqualified_count

Returns quota-qualification statistics: Value = quota-qualified responses, Total = all responses.

get_quota_qualified_count

Returns a contact of a survey's contact list by PersonalizedID: name, email, language, custom fields, completion state and the contact's personal survey link. surveyLink is the contact's PERSONAL survey link — responses through it are attributed to this contact.

get_respondent

Returns overall response counts for a survey: Total = all responses (started), Value = completed responses.

get_response_counts

Returns response counts per calendar day for the last 14 days, including days with zero responses: per day, Total = responses started, Value = completed.

get_response_counts_by_date

Returns response counts grouped into exactly three device buckets: monitor, tablet, cellphone. ColumnName = bucket name; per-bucket Total = all, Value = completed.

get_response_counts_by_device

Returns response counts grouped by traffic source. ColumnName = lower-case source name; Total and Value are PER-SOURCE (all/completed responses for that source), not survey-wide.

get_response_counts_by_source

Returns one respondent's response (result case): answers in Items (each addresses a question by variable name, e.g. Q1, Q2.3), device, browser, platform, source, language, duration, completion state and timestamps. resultCaseID is the response's stable identifier — the key for de-duplicating incremental reads via list_survey_responses' ChangedSince. Respondent contact / personal data is not returned through this API.

get_survey_response

Returns the survey structure for a survey code: questions with their variable names (Q1, Q2.3 for a checkbox option, Q<CustomID>), question texts, types and answer options with numeric codes, plus the page layout: each question carries page (1-based) and pageTitle, and pages lists every page in order (number, title, questionCount, isEnd, marksComplete) INCLUDING pages that are still empty. logic lists the survey's stored rules in the authoring vocabulary — display rules (target question, show|hide, match, conditions) and jumps (source question, operator, value, target page number or 'end') — audit them before adding new ones; logic.errors lists BROKEN rules (their source question/option or target page was deleted) — each needs the user's decision: delete the rule block or redefine it. languages lists the survey's default language and every configure_survey_language layer (code, own name, direction, isDefault, translated/fallback key counts). archived:true means the survey sits in the recoverable bin (it is hidden from list_surveys; the user restores it in the app). Use the variable names to interpret responses and address answers when creating or updating a result case; use the page layout to place questions (add_question's page) and to plan branching (a branching source must sit on an earlier page than its targets). This structure is also the key to interpreting raw responses from list_survey_responses when you run your own analysis. shareURL is the canonical link respondents open and previewURL opens the survey in test mode (nothing is stored) - these are the canonical survey URLs; a survey URL assembled from other parts is not a supported link.

get_survey

Returns a webhook's recent delivery attempts, newest first: timestamp, HTTP statusCode the target answered with (0 = unreachable), isSuccess (2xx) and isRetry (a retry of an earlier failed delivery). Use it to check whether a webhook is healthy and whether the target endpoint accepts QUESTIONSTAR's events. Webhook IDs come from list_webhooks.

get_webhook_deliveries

Lists the account's ARCHIVED surveys — the ones sitting in the recoverable bin (archive_survey put them there, or the user deleted them in the app). Returns for each: ID, Name, Code, the SurveyState it had before archiving, and DeleteDate (when it was binned). Read-only: this does NOT restore or delete anything — the user restores an archived survey, or permanently deletes it, in the QUESTIONSTAR app. Use it to show the user what is in the bin, e.g. after archiving drafts. Live surveys and permanently deleted surveys are not listed.

list_archived_surveys

Lists the LAYOUT templates available to the account: its own templates and the built-in system templates. A layout template styles a survey's appearance — it is NOT a survey to clone from (use list_surveys + clone_survey for that). Pass a template's ID to apply_layout. Survey-dedicated copies created by apply_layout's custom CSS appear here as 'API Layout {code}'.

list_layout_templates

Returns QUESTIONSTAR's layout design-token vocabulary for apply_layout's inlineTokens: the UI-editable tokens (uiControlled — reflected in the Layout Editor), known code-only tokens (style the survey but are invisible in the editor), a set of commonly used tokens, and known pitfalls. Only these names are consumed by the survey player; an unknown name is written as a CSS custom property that nothing consumes.

list_layout_tokens

Returns all responses of a survey as a tabular data set: Questions describes the columns (question variables Q1…Qn, A/B tests T1…Tn), Cases holds one row per response, newest first. Filters combine: FromDate/ToDate compare against each response's StartDate (inclusive; send explicit-offset timestamps — UTC 'Z' — or they are read in server-local time); ChangedSince returns only responses created or changed at or after the given moment; because persistence is asynchronous, incremental reads use an overlapping window and are de-duplicated by resultCaseID, each response's stable identifier; Device narrows to a device bucket (monitor/tablet/cellphone), Source to a traffic source (responses submitted via this API are 'external'). Counted against the heavy rate class (600 requests/hour). For large data sets export_survey_responses returns the same data as a temporary file link. The column definitions in Questions (variable names, question types, option codes) are the key to interpreting each row; the same structure is returned by get_survey. Respondent contact / personal data is not returned through this API.

list_survey_responses

Lists all surveys of the account that owns the API token. Returns for each: ID, Name, Code (the 8-character code every other tool takes as 'code'), SurveyState, CreationDate, LastChangedDate, plus shareURL (the canonical link respondents open) and previewURL (test mode - shows the survey but stores nothing). shareURL and previewURL are the canonical survey links; the host differs per instance.

list_surveys

Lists a survey's webhook subscriptions — survey events pushed as JSON POST to an https URL. Returns for each: ID (pass it to get_webhook_deliveries), targetURL, eventType (ResponseRecieved = a response was submitted or updated; SurveyPublished = the survey was (re)started), includeFields (variables included in the payload; empty = all), answersAsText and useCustomID payload options. Only reads the configuration; create_webhook, delete_webhook and test_webhook perform the corresponding actions. Includes hooks made in the app or via integrations like Zapier/n8n.

list_webhooks

Pauses a survey: a RUNNING survey stops accepting NEW responses. HIGH-CONSEQUENCE action on a live survey — get the user's EXPLICIT consent before calling with confirm:true; call WITHOUT confirm first, which is a read-only PREVIEW with zero side effects (live state, response counts, concurrency slots), and show the user what pausing means. Pausing is REVERSIBLE — publish_survey re-starts the SAME publication and collection resumes into the SAME dataset (PublicationID unchanged, nothing deleted). Respondents currently mid-response will finish and be saved — only NEW entries are closed; a new visit to the share link sees the survey-closed page. Pausing frees one of the concurrent-survey slots. Guards: a never-published survey is refused ('there is nothing to pause'); pausing an already stopped survey (including one that auto-closed) is idempotent success with wasAlreadyStopped. The paused state is verified server-side by re-reading the publication before success is reported.

pause_survey

Publishes a survey — starts collecting responses — and returns the public share link respondents open. Idempotent: publishing an already running survey is not an error; the current state comes back with wasAlreadyStarted=true. The started state is verified server-side by re-reading the publication before success is reported. The account's limit on concurrently running surveys is enforced: when it is reached the call fails with a message naming the limit and the current count — relay it; the user can stop another survey first. Publishing also fires the survey's SurveyPublished webhooks, if any are configured. Uses the same start flow as the application UI — never creates duplicate publications. Once published, responses start collecting on the share link and the survey counts against the account's concurrent-survey limit. Surveys can also be published from the app.

publish_survey

Reorders a survey's pages and returns the current page list (number, title, question count, flags). order is the full list of the current 1-based page numbers in their new sequence — a permutation of every page, as get_survey reports them. Show/skip logic fires on the move BETWEEN pages: a branching source question takes effect only on questions placed on a later, separate page, so keep each source page before the pages it gates. Verified by readback. Requires the edit-survey right on this survey.

reorder_survey_pages

This is QUESTIONSTAR's built-in, server-side computation on the survey's responses. The same and other statistics (e.g. multivariate/interaction regression, time-series, ANOVA) can be computed from the raw responses returned by list_survey_responses. Computes pairwise correlations between survey variables: one matrix per requested method (pearson default; spearman for ordinal/non-normal data; tau = Kendall). Variables are addressed by question codes as returned by get_survey: Q1 (whole question), Q3.1 (matrix row), Q2.3 (checkbox option — enters as 0/1). Analyzable: choice questions (options enter by their numeric export code), checkbox options, numeric, slider and sorting questions; free-text cannot be analyzed. Each cell carries the pair's coefficient r (−1…1), its two-sided pValue, fisherZ (Pearson) and n = the number of response pairs used — missing answers are excluded PAIRWISE, so n varies per cell. Uncomputable pairs (e.g. a constant variable) carry an error instead of numbers. Heavy rate class (600 requests/hour).

run_correlation

This is QUESTIONSTAR's built-in, server-side computation on the survey's responses. The same and other statistics (e.g. multivariate/interaction regression, time-series, ANOVA) can be computed from the raw responses returned by list_survey_responses. Computes a LINEAR REGRESSION of one survey variable (dependent) on one or more predictors. Variables are addressed by question codes as returned by get_survey: Q1 (whole question), Q3.1 (matrix row), Q2.3 (checkbox option — enters as 0/1). Analyzable: choice questions (options enter by their numeric export code), checkbox options, numeric, slider and sorting questions; free-text cannot be analyzed. Responses missing ANY model variable are excluded LISTWISE. The result uses POSITIONAL header contracts: modelSummaryHeader[i] names modelSummary[i] (R², adjusted R², …); anovaHeader names the columns of each anova row; coefficientNames[i] names coefficients[i] — each coefficient row holds estimate, standard error, t and p in the header's order. coefficientsWarnings carries engine warnings such as collinearity. The regression runs on the server's R engine; if it is unavailable the call returns an error envelope. Heavy rate class (600 requests/hour).

run_regression

This is QUESTIONSTAR's built-in, server-side computation on the survey's responses. The same and other statistics (e.g. multivariate/interaction regression, time-series, ANOVA) can be computed from the raw responses returned by list_survey_responses. Computes a PAIRED-samples t-test between exactly two survey variables answered by the same respondents (e.g. a before/after item pair). Variables are addressed by question codes as returned by get_survey: Q1 (whole question), Q3.1 (matrix row), Q2.3 (checkbox option — enters as 0/1). Analyzable: choice questions (options enter by their numeric export code), checkbox options, numeric, slider and sorting questions; free-text cannot be analyzed. Returns descriptive statistics of both samples (mean, stdDev, stdErrMean, min/max, median, variance), n = the number of complete pairs (responses missing either value are excluded), and the test set: meanDiff with its 95% confidence interval (confIntervalLower/Upper), Student's t (studentT), degrees of freedom (df) and the two-sided pValue. When the test cannot be computed, the result's 'error' field explains why. Heavy rate class (600 requests/hour).

run_t_test

Sets the survey's GLOBAL end-screen message — replaces the standard 'Thank you for participation…' text respondents see when they finish. Writes the survey's default language; other languages are set through configure_survey_language. HTML is allowed; an optional title renders above the message. The message is shown only when the survey ends on the standard end screen: with a redirect or restart end behavior the text is saved but not displayed — the reply's willDisplay reports which case applies (the end behavior is changed in the app's survey settings). Distinction: this is the GLOBAL final (also where a add_jump_logic_rule target='end' branch lands); for a BRANCH-specific final text use add_end_page and jump to its page number. Verified by re-reading the stored survey. Requires the edit-survey right.

set_end_message

Sets a page's flags and returns the current page list (number, title, question count, flags). page is the 1-based number of the page. markComplete=true marks the response COMPLETED once the respondent passes that page — for surveys where the required part ends mid-flow and the rest is optional (e.g. demographics); it counts in the completed statistics. isEnd=true turns the page into an end page (the survey finishes on it with its own content) — usually you want add_end_page instead. A flag that is omitted stays unchanged. Verified by readback. Requires the edit-survey right on this survey.

set_survey_page_flags

Returns QUESTIONSTAR's survey-design checklist. Use when the user asks to design, review or improve a survey.

survey_quality_guidelines

Sends a REAL test delivery (a sample event, in the exact shape real deliveries use) to the webhook's target URL — the external endpoint WILL receive an actual request. Confirm with the user first: call WITHOUT confirm for a read-only PREVIEW, then again with confirm:true. The webhook is verified server-side before firing (unknown ID → 'Webhook not found.'); verify the delivery outcome with get_webhook_deliveries (the attempt's statusCode).

test_webhook

Edits an EXISTING question in place: title, answer requirement (none|soft|strict), custom ID, and the option list. Options are matched by their export CODE (the numbers get_survey reports): a matching option is relabeled IN PLACE — its identity, collected answers and logic references stay intact; a new code is added as a new option; a code MISSING from the submitted list is REMOVED. Always pass the FULL desired option list — a partial list removes the options you left out. Removing options from a survey that already has responses is HIGH-CONSEQUENCE: it retroactively re-interprets collected data and cannot be undone (re-adding creates a new identity) — the call fails with a warning unless confirm:true; get the user's EXPLICIT consent first. Changing the question TYPE is not supported — delete_question and add_question instead. The reply reports the applied changes, response count and any logic rules referencing the question, verified by re-reading the stored survey. Requires the edit-survey right.

update_question