> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Surveys

> What the Surveys module does, who can use it, and how a survey moves from a draft questionnaire to a compiled call script, live calls and results.

<Note>Surveys is in beta and available to accounts enabled by the Voxworks team. Speak to the Voxworks team if you would like access.</Note>

## What is Surveys?

**Surveys** is where you *"Upload, author and publish surveys your AI voice agents run."* You write a questionnaire — sections, questions, answer options, routing rules and outcomes — and Voxworks turns it into an AI interviewer that asks it over the phone, the way a CATI (computer-assisted telephone interviewing) interviewer would.

You'll find it in the sidebar under **Outbound Calls → Surveys**, between **Batch Scheduler** and **Automations**. The entry only appears for accounts that have Surveys enabled.

A survey is made of two parts:

* **Your questionnaire** — the authored sections and the questions inside them, plus the routing rules, survey variables and outcome codes that decide who is asked what and how the interview ends.
* **A fixed shell** — the parts every survey has and that you fill in rather than build: the **Agent** (who is calling, the voice and the survey-wide defaults), the **FAQs**, the **Behaviours** (busy and stop), the **Gatekeeper** (how the call opens and asks for consent) and the **Closing** (the farewell and the closing line for each outcome).

You don't design call flows by hand. When you compile, Voxworks builds an ordinary [call script](/scripts/overview) and its flows from the survey. That script is what places or answers the calls, and every answer the respondent gives is recorded back against the survey so you can read it in **Results**.

***

## How a survey gets from draft to results

| Stage               | What happens                                                                                                                                                                   | Read more                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| **1. Create**       | Start a survey from scratch (or import a Voxworks JSON definition). It opens as version **v1**, a draft, with one section called **Main survey**.                              | [Create a survey](/surveys/create-a-survey), [Importing surveys](/surveys/import)  |
| **2. Author**       | On the **Questions** tab, fill in the fixed sections and add your own sections and questions. Add routing on the **Logic** tab.                                                | [Questions tab](/surveys/questions-tab), [Logic tab and canvas](/surveys/logic)    |
| **3. Check**        | The **Readiness** tab lists **blockers** (which stop a compile or publish) and **warnings** (which don't).                                                                     | [Readiness](/surveys/readiness)                                                    |
| **4. Compile**      | **Validate** (or **Compile** on the Readiness tab) builds the call script in the background. The script appears in **Call Scripts**, named after the survey.                   | [Validate, compile and publish](/surveys/validate-compile-publish)                 |
| **5. Publish**      | **Publish** freezes this version as the live one. The previously published version is retired. Published versions can't be edited — you create a new draft to change anything. | [Versions and drafts](/surveys/versions)                                           |
| **6. Run**          | Dial the compiled script from **Batch Scheduler**, or point an inbound number at it, like any other script.                                                                    | [Running a survey](/surveys/running-a-survey)                                      |
| **7. Read results** | **Results** shows completion, drop-off, per-question answers, outcomes and individual responses, and exports a CSV.                                                            | [Results](/surveys/results), [Responses and export](/surveys/responses-and-export) |

<Warning>A survey has no default voice. Choose one under **Voice** in the **Agent** section before you compile — a script compiled without a voice cannot place a call. See [Agent section](/surveys/agent).</Warning>

Every survey created in the app runs on the **voice** channel in English. Both are shown read-only on the Readiness tab as **Channel** and **Language**. A Voxworks survey runs in both directions — the same compiled script handles outbound calls and respondents who call back.

***

## What a respondent experiences

On every call, the [Gatekeeper](/surveys/gatekeeper) runs first. It works out who has picked up — a live person, a receptionist or call-screening service, or an answering machine — and asks for consent with your greeting. A "yes" starts the questionnaire; a "no", a "call me later", a wrong number or a voicemail ends the call with the matching outcome.

Inside the questionnaire the interviewer asks each question in order, following your routing rules. Along the way it:

* re-reads a question in different words when asked, or when it hears nothing ([Avoiding repetition](/surveys/repetition));
* nudges once on a "don't know" or a refusal before recording the question as skipped ([Attempts and step levels](/surveys/attempts-and-step-levels));
* checks a possible mishearing with a short "did you say…?" ([Answer confirmation](/surveys/answer-confirmation));
* answers questions about the call from your [FAQs](/surveys/faqs), then returns to the question it was asking;
* ends the call politely when the respondent is busy or wants to stop ([Behaviours](/surveys/behaviours)).

The interview ends with an outcome code, the closing line you wrote for that outcome, and your farewell ([Closing and outcomes](/surveys/closing-and-outcomes)).

***

## Question types

| Type                                                   | Use it for                                                          |
| ------------------------------------------------------ | ------------------------------------------------------------------- |
| [Display](/surveys/question-types/display)             | A statement read out with no answer — an introduction or a notice.  |
| [Single choice](/surveys/question-types/single-choice) | One answer from a list the interviewer reads out (or listens for).  |
| [Rating](/surveys/question-types/rating)               | A scale, such as 1 to 5 or "very satisfied" to "very dissatisfied". |
| [Battery (grid)](/surveys/question-types/battery)      | Several items rated one after another against the same scale.       |
| [Number](/surveys/question-types/number)               | A spoken number — a postcode, an age, a count or a 0–10 score.      |
| [Long text](/surveys/question-types/long-text)         | An open answer in the respondent's own words.                       |
| [First name](/surveys/question-types/first-name)       | Collecting or confirming the respondent's first name.               |
| [Phone number](/surveys/question-types/phone-number)   | Collecting or confirming an Australian phone number.                |

Settings every question shares are covered in [Question settings](/surveys/question-settings).

***

## Permissions

Surveys uses its own permissions. The Owner role has all of them; the Member role has the first three. The team's primary owner always passes every check. See [Roles & Permissions](/team/roles-permissions) for how roles work.

| Permission                    | Owner | Member | What it allows                                                                                  |
| ----------------------------- | ----- | ------ | ----------------------------------------------------------------------------------------------- |
| `surveys.view`                | ✓     | ✓      | Following a compile or publish job's progress.                                                  |
| `surveys.create`              | ✓     | ✓      | The **New survey** menu, **Create Voxworks copy**, and importing.                               |
| `surveys.edit`                | ✓     | ✓      | Editing drafts, **Archive**, **Create draft**, **Upload new version**, and saving **Settings**. |
| `surveys.publish`             | ✓     | —      | **Compile**, **Publish**, and the compile that **Validate** starts.                             |
| `surveys.responses.export`    | ✓     | —      | **Export** and **Download CSV** in Results.                                                     |
| `surveys.responses.sensitive` | ✓     | —      | Seeing the respondent key on an individual response.                                            |

***

## Next Steps

* [Create a survey](/surveys/create-a-survey) — the fastest path from an empty list to a first published survey.
* [Survey workspace](/surveys/survey-workspace) — the header, tabs and toolbar you'll work in.
* [Question settings](/surveys/question-settings) — what every question can be told to do.