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

# Data Collection - v0.2

> The standard composite tool for collecting and verifying one data field from a caller by voice — its three collection types (user name, phone number, alphanumeric), inputs, outputs and wiring conventions.

## What it does

**Data Collection - v0.2** is the standard way to collect and verify **one** field from a caller by voice — a name, a phone number, or an alphanumeric code such as a policy or booking reference. You place one tool step in your flow; on the call it runs a complete collection exchange:

* the first ask (with an optional custom opening line),
* confirmation read-back of what was heard,
* optional spelling and spell-back verification,
* correction loops with attempt limits, so a mis-heard value gets fixed rather than saved,
* a quick confirm of a pre-existing value instead of asking fresh, and
* skipping entirely when the value is already known.

It is a [composite tool](/tools/composite-tools): the whole exchange runs behind a single step, and the caller experiences it as a natural part of the conversation. Each use collects exactly one field — to collect a first name and a mobile number, place two Data Collection steps.

***

## Collection types

The **Type** input selects one of three collection behaviours. Choose the type that matches the data, not just the prompt wording — each type verifies differently.

### User name

For names and other short spoken words. The assistant asks for the value, reads it back for confirmation (when **Confirm** is on), and can ask the caller to spell it and spell it back for final verification (when **Spell** is on). A pre-populated **Existing Value** is tidied up and quick-confirmed rather than asked fresh.

Use it for first names, last names, and similar single-word or short answers where the caller says the value rather than dictating characters.

### Phone number

For phone numbers. Verification works digit-by-digit rather than by a separate confirmation question: the assistant reads the number back in short spoken groups of digits and the caller corrects any digit by its position, with the country prefix kept intact. If the caller already volunteered their number in the last few turns of conversation before this step, the tool picks it up and goes straight to the read-back instead of asking again. An **Existing Value** is sanity-checked (it must look like a complete number) before being quick-confirmed.

### Alphanumeric

For codes that mix letters, digits and symbols — reference numbers, booking codes, registration plates. Values of up to 10 characters are accepted. The read-back spells the value unambiguously: letters use phonetic words (*A for Alpha*), digits are read as digit names, and symbols are named (*dot*, *dash*), in short groups so the caller can follow along. Case is preserved exactly as collected, corrections are made character-by-character, and — like phone numbers — a code the caller already mentioned in recent turns is picked up without re-asking.

***

## Inputs

| Setting               | Description                                                                                                                                                                                                                                    | Default          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| **Type**              | What is being collected: `user name`, `phone number` or `alphanumeric`. Selects the per-type collection behaviour above. Literal select, required.                                                                                             | —                |
| **Field Description** | Human-readable label used in all prompts, e.g. `First Name` or `Mobile Number`. Literal, required.                                                                                                                                             | —                |
| **Confirm**           | Read the collected value back and ask the caller to confirm it. Literal toggle.                                                                                                                                                                | On               |
| **Spell**             | Ask the caller to spell the value, then spell it back for final verification. Literal toggle.                                                                                                                                                  | Off              |
| **Existing Value**    | A pre-populated value, typically a variable such as `{{contact.first_name}}` (string, e.g. `Jane`). If present, the assistant quick-confirms it instead of asking fresh.                                                                       | —                |
| **Skip If Set**       | A variable reference, typically the same `{{contact.*}}` field the output writes to — e.g. `{{contact.first_name}}` (string, e.g. `Jane`). If it resolves to a real value the step ends immediately with a true result and no questions asked. | —                |
| **First Message**     | Custom opening line for the first ask when there's no existing value, e.g. "So I can get your details right, could I start with your first name?" — should end with a question mark. Literal or variable.                                      | Standard wording |
| **Data Context**      | Extra context the assistant can use to answer the caller's questions about the field (e.g. why you need it), and may share proactively when it helps the caller complete it. Literal or variable.                                              | —                |

**Confirm** and **Spell** shape the user-name exchange; for phone numbers and alphanumeric codes the grouped read-back described above is itself the verification, so those types always read the value back regardless of the toggles.

***

## How a collection runs

Every use of the tool enters through the same gate, in this order:

1. **Skip If Set** — if the referenced variable already holds a real value, the step ends immediately with a true result. Nothing is spoken.
2. **Existing Value** — if a pre-populated value is present (and isn't a placeholder), the assistant quick-confirms it: "I have your first name as Jane — is that right?" A yes keeps it; a no drops into the normal collection exchange.
3. **Recent turns** — for phone numbers and alphanumeric codes, the tool checks whether the caller already volunteered the value in the last few turns; if so it goes straight to the read-back.
4. **Fresh ask** — otherwise the assistant asks for the value, using **First Message** if you set one.

From there the confirmation, spelling and correction loops run as the type requires. Each stage of the exchange (asking, confirming, spelling) has an attempt limit of five; when a limit is reached the tool gives up gracefully and finishes with a false result rather than trapping the caller in a loop.

***

## Outputs

| Output              | Description                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------- |
| **result**          | Hidden boolean — routes the step. True when a value was collected (or Skip If Set fired).    |
| **Collected Value** | The confirmed value as a string. Map it to the matching contact field in **Output mapping**. |

## Variables this tool writes

| Variable                               | Type    | Example | Description                                                                       |
| -------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------- |
| `{{data_collection.output_result}}`    | string  | `Jane`  | The confirmed collected value — the source behind the **Collected Value** output. |
| `{{data_collection.output_extracted}}` | boolean | `true`  | Internal signal that a value was extracted during the exchange.                   |

The `data_collection` namespace also holds `temp_*` working fields — private to the tool. A later Data Collection step overwrites the whole namespace, so always map **Collected Value** to a durable variable rather than reading `{{data_collection.output_result}}` in later steps.

***

## Routing and wiring tips

* **true** — value collected (or skipped because it was already set). **Otherwise** — collection failed (attempt limits reached or the caller refused).
* For an optional field, point true and otherwise at the **same** next step so a failed collection never blocks the call.
* Use the standard contact fields for standard data: wire **Existing Value** and **Skip If Set** to the `{{contact.*}}` field being collected, and map **Collected Value** back to that same field. Don't invent custom variables for names, phones or emails.
* If the contact record already holds the value and you skip the **Existing Value** input, the caller gets asked from scratch instead of a quick confirm.
* Point **Skip If Set** at the same variable the output writes to, so repeat visits to the step skip cleanly instead of re-collecting.
* To collect an email address, use [SMS | Get Valid Email](/tools/composite/sms-get-email) instead — emails are far more reliable over an SMS round-trip than spelled aloud.

***

## Next Steps

* [Composite Tools](/tools/composite-tools) — how composite steps run, and how inputs, results and outputs connect to your call.
* [SMS | Get Valid Email](/tools/composite/sms-get-email) — collect a validated email address by SMS round-trip.
* [Tool Steps](/flows/steps-tool) — configuring inputs, conditions and output mapping on a step.
* [Variables](/flows/variables) — the full reference of variables tools read and write.