> ## 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.

# Create a survey

> Start a new survey from scratch with the Start a new survey dialog, see what it creates, and follow a walkthrough from an empty draft to a first published survey.

## Start a new survey

You need the `surveys.create` permission.

1. Go to **Outbound Calls → Surveys**.
2. Click **New survey ▾** and choose **Start from scratch** — *"Blank survey with an empty draft version"*.
3. The **Start a new survey** dialog opens: *"Create a native Voxworks draft with a ready-to-edit first section."*

| Field           | Required | Notes                                                                                                                            |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Survey name** | Yes      | Up to 500 characters. Placeholder: *"e.g. Customer satisfaction follow-up"*. The compiled call script is named after the survey. |
| **Description** | No       | Placeholder: *"What this survey measures and when it should run"*. Shown under the name in the list.                             |

4. Click **Create survey** (it reads **Creating…** while it saves). The toast *"Survey created"* appears and the new survey opens in the [survey workspace](/surveys/survey-workspace).

You can change the name and description later on the [Settings tab](/surveys/settings-tab).

### What a new survey contains

* **Version v1**, with the status *draft* — the only version you can edit until you publish.
* **One section**, titled **Main survey** (key `main`), ready for your first question.
* **The fixed sections** — Agent, FAQs, Behaviours, Gatekeeper and Closing — empty, waiting for you to fill them in.
* **Moving-on lines turned off** — the interviewer won't say "Alright" or "Noted" after each answer unless you turn it on. See [Agent section](/surveys/agent).

A new survey starts with **blockers** on the Readiness tab — it has no questions, no greeting and none of the outcome codes every survey needs. The walkthrough below clears them.

If you already have a survey definition in Voxworks JSON, you can [import it](/surveys/import) instead. To start from an existing survey, use **Create Voxworks copy** on the [Surveys list](/surveys/surveys-list).

***

## Walkthrough: from empty draft to first publish

Work down the **Outline** on the [Questions tab](/surveys/questions-tab). Each fixed section has its own form with a **Save** button.

### 1. Agent — who is calling

Open **Agent** and fill in **Agent name**, **Organisation** and **Study name**, then choose a **Voice**. The outbound greeting (step 2) is spoken exactly as you write it, so name the agent and organisation there too; a respondent who calls back hears the organisation and the study name.

<Warning>There is no default voice. If you don't choose one, Readiness warns *"No voice is chosen — the compiled script will carry none and cannot place a call."*</Warning>

This is also where the survey-wide attempt caps and step levels live. The defaults are a sensible start. See [Agent section](/surveys/agent) and [Attempts and step levels](/surveys/attempts-and-step-levels).

### 2. Gatekeeper — the greeting and consent

Open **Gatekeeper → Outbound** and write the **Greeting**. It is the first thing a person hears, and it must **end with the consent question** — for example *"Hi, it's Alex from Acme Research. We're running a short survey about local services and would love your views. Are you happy to take part?"* An empty greeting is a blocker. See [Gatekeeper](/surveys/gatekeeper).

Decide what an answering machine gets under **Voicemail - Message** and **Voicemail - SMS** — see [Voicemail and SMS](/surveys/voicemail).

### 3. FAQs — what respondents will ask

Add answers to the questions people ask interviewers: *who is calling?*, *how long will this take?*, *where did you get my number?*, *what is it for?*, *what happens to my answers?* Without them the interviewer has no answer for these. See [FAQs](/surveys/faqs).

### 4. Your questions

Under **Main survey** in the outline, click **Add question**. Pick a **Type**, write the **Voice prompt** — the words the interviewer reads out — and fill in the type's own settings. Click **Add question** at the bottom of the pane to save it.

* For a list of answers, use [Single choice](/surveys/question-types/single-choice) or [Rating](/surveys/question-types/rating).
* For a statement with no answer, such as a recording notice, use [Display](/surveys/question-types/display).
* For open feedback, use [Long text](/surveys/question-types/long-text).

Add more sections with the **+** beside **Outline** when the questionnaire has distinct parts. See [Sections](/surveys/sections) and [Question settings](/surveys/question-settings).

### 5. Routing (optional)

If some respondents should skip questions or be screened out, add rules on the **Logic** tab. Without rules, everyone is asked every question in order. See [Routing rules](/surveys/routing-rules).

### 6. Closing — outcomes and farewell

Open **Closing**. Write the **Farewell** — spoken last on every call where someone is on the line. Then add the four outcome codes every survey ends with: `completed`, `callback_requested`, `refused` and `no_contact`. The alert at the top of the section lists any that are missing, with an **Add them** link. Give each a closing text. See [Closing and outcomes](/surveys/closing-and-outcomes).

### 7. Check readiness and compile

Click **Validate** in the header. It opens the **Readiness** tab, and when there are no blockers (and you have the `surveys.publish` permission) it starts a compile. A badge beside the survey name reads **Queued…**, then **Compiling…**, and the toast *Compiled for voice* confirms it has finished — typically in under a minute or two. See [Readiness](/surveys/readiness) and [Validate, compile and publish](/surveys/validate-compile-publish).

### 8. Test

The compiled script appears in **Call Scripts**, named after the survey. Place a test call to it and listen to the whole interview, including a "no" at the greeting and a "don't know" on a question. See [Running a survey](/surveys/running-a-survey).

### 9. Publish

When you're happy, click **Publish**. The version becomes *published* and can no longer be edited — to change anything later, create a new draft from **Version history**. See [Versions and drafts](/surveys/versions).

***

## Next Steps

* [Survey workspace](/surveys/survey-workspace) — the header, tabs and toolbar.
* [Question settings](/surveys/question-settings) — what every question can be told to do.
* [Running a survey](/surveys/running-a-survey) — putting the compiled script on the phone.