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

# Number

> The Number question type: a spoken number such as a postcode, age, count or 0–10 score. Covers the Format check (pattern or range), Screen out, Format hint, confirmation, what the respondent hears, and what is recorded.

## What it's for

A **Number** question collects a number the respondent says — a postcode, a year of birth, an age, how many people live in the household, or a score from 0 to 10.

Spoken numbers are turned into digits before they're checked: *"three nine four one"*, *"3 9 4 1"* and *"postcode 3941"* all become `3941`.

***

## Settings

Alongside the settings every question shares ([Question settings](/surveys/question-settings)):

| Setting                                   | What it does                                                                                                                                                                         | Default    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| **Format**                                | What a usable answer looks like: **None**, **Pattern** or **Range**. See below.                                                                                                      | **None**   |
| **Screen out unless the value is one of** | A list of accepted values, one per line (up to 500). A well-formed answer that isn't on the list is recorded, then the respondent is screened out. *"Leave empty to screen nobody."* | Empty      |
| **Outcome**                               | Appears once the screen-out list has values. *"What the call is recorded as, and whose closing text the respondent hears. Add the text in Outcomes."*                                | `excluded` |
| **Format hint**                           | A short description of the expected answer, such as *"a four-digit postcode"*. *"Folded into the clarify line: “I didn’t quite catch the number — could you say it again?”"*         | Empty      |
| **Read every answer back**                | Reads the number back as digits for a yes before recording it.                                                                                                                       | Off        |

A Number question has no answer options and no **Screen out if the question cannot be run** switch.

### Format

*"What a usable answer looks like. An answer of the wrong shape is not understood at all, so the agent asks again; only when the attempts run out does the question record it as invalid."*

| Option      | Use it for                                                        | How to set it                                                                                                                                                     |
| ----------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **None**    | Any number.                                                       | —                                                                                                                                                                 |
| **Pattern** | A fixed shape, such as a four-digit postcode or a postcode range. | A regular expression, checked against the answer as digits. See the examples below.                                                                               |
| **Range**   | A number between two limits, such as an age or a 0–10 score.      | **Minimum** and **Maximum**. Leave either blank for no limit (*"Any"*), but not both — a range with no limits, or a minimum above the maximum, fails the compile. |

Pattern examples:

* `^[0-9]{4}$` — any four-digit postcode.
* `^39(3[6-9]|4[0-4])$` — postcodes 3936 to 3944 (the field's placeholder).
* `^(19|20)[0-9]{2}$` — a year from 1900 to 2099.

As you type, the field confirms *"This is a valid regular expression."* or explains what's wrong.

Always start a pattern with `^` and end it with `$`. Without them, the pattern matches if it appears *anywhere* in the answer. An invalid pattern is a readiness blocker: *"… validation pattern is not a valid regular expression."*

### Format and Screen out are different

* **Format** decides whether an answer is *usable*. An answer of the wrong shape is treated as not heard properly, and the interviewer asks again.
* **Screen out** decides whether a *usable* answer *qualifies*. The answer is recorded either way; a non-qualifying one then ends the interview under the chosen **Outcome**.

For example, a survey of one council area might set **Format** to a four-digit pattern and list the area's postcodes under **Screen out unless the value is one of**. A respondent who says *"4000"* has their postcode recorded, hears the closing text for the `excluded` outcome and the farewell, and the call ends.

<Warning>The screen-out outcome needs to exist in **Closing**, with a closing text. Readiness warns if it's missing (*"… screens respondents out as “excluded”, which is not listed in Outcomes — they hear nothing but the farewell."*) or has no text. See [Closing and outcomes](/surveys/closing-and-outcomes).</Warning>

To screen on a number, use the question's own screen-out list rather than a rule. Other routing on the answer (jump, show, hide, set variable) works as usual; see [Routing rules](/surveys/routing-rules).

If Readiness warns that a question *"still stores the retired “allowed values” validation"*, open the question and save it once. The list works as a screen either way.

***

## What the respondent hears

**The ask.** The voice prompt on its own — no lead-in, no hint.

**An answer of the wrong shape** gets a clarify line with your **Format hint** folded in — *"Sorry, I didn't quite catch the number — could you say it again? I'm after a four-digit postcode."* When the attempts run out, the question is recorded as `invalid` with the last digits heard, and the interviewer moves on gently.

**Confirmation.** With **Read every answer back** on, the number is read back digit by digit — *"3 9 4 1 — is that right?"* With it off (the default), a well-formed number is recorded straight away. There is no "did you say…?" mishearing check on numbers. Turn read-back on for postcodes, years and dollar amounts; leave it off for short scores.

**"I don't know"** gets one nudge — *"No worries — is it one you could have a guess at?"* — then the question is skipped.

**A refusal** gets one reassuring nudge — *"That's completely fine — it's only used with everyone else's, never on its own. Would you be happy to give it?"* — then the question is skipped.

Silence, "say that again", FAQs, busy and stop work as on any question — see [Question settings](/surveys/question-settings#what-happens-when-the-interviewer-asks).

### A 0–10 score

For a likelihood or satisfaction score out of 10, use a Number question with **Range** 0 to 10, and explain the scale in the prompt: *"On a scale from 0 to 10, where 0 is not at all likely and 10 is extremely likely, how likely are you to recommend …?"* Eleven points is too many to read out as a [Rating](/surveys/question-types/rating).

***

## What is recorded

| Variable                                 | Type | Example    | Notes                                                                                                                |
| ---------------------------------------- | ---- | ---------- | -------------------------------------------------------------------------------------------------------------------- |
| `{{survey.<key>.result}}`                | text | `3941`     | The number as digits. A leading zero is kept (`0800`). Empty when skipped; the last digits heard when `invalid`.     |
| `{{survey.<key>.status}}`                | text | `captured` | `captured`, `skipped`, `invalid`, `abandoned`, or empty if never reached. A screened-out answer is still `captured`. |
| `{{survey.<key>.screened}}`              | text | `true`     | `true` when a well-formed answer wasn't on the screen-out list; otherwise `false`.                                   |
| `{{survey.<key>.termination_requested}}` | text | `true`     | `true` when this answer ended the interview.                                                                         |

In Results and the CSV export, the answer is stored as a number, so it can be averaged and summed. Because of this, a leading zero isn't kept in the export — `0800` appears as `800`. If leading zeros matter (Northern Territory postcodes, for example), pad them back when you analyse the export. See [Responses and export](/surveys/responses-and-export).

***

## Next Steps

* [Question settings](/surveys/question-settings) — the shared fields.
* [Closing and outcomes](/surveys/closing-and-outcomes) — the text a screened-out respondent hears.
* [Answer confirmation](/surveys/answer-confirmation) — read-back across question types.