> For the complete documentation index, see [llms.txt](https://docs.borndigital.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borndigital.ai/digital-agent/tools-reference/numbers-amounts-and-identifiers.md).

# Numbers, amounts & identifiers

Numbers, amounts, currencies and identifiers such as birth numbers or registration plates.

Numbers, amounts, currencies and identifiers such as birth numbers or registration plates. How to add a tool and use its result is described in [Tools & smart functions](https://docs.borndigital.ai/digital-agent/tools-reference.md).

| Tool                           | Technical name               | What it does                                                                                                                                                                                                                | Languages                          |
| ------------------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| Advanced number                | `advanced_number`            | Extract numbers from user input according to specified criteria, supporting grouping of digit sequences, leading zeros, and optional summing, pattern matching, and custom input.                                           | any                                |
| Amount extractor               | `amount`                     | Extract monetary amounts with their decimal part and pair each one with the currency standing next to it.                                                                                                                   | sk                                 |
| Birth number                   | `birth_number`               | Extract and validate Czech, Slovak, Polish, and Romanian birth numbers from user input.                                                                                                                                     | cs, pl, sk, ro                     |
| Currency extractor             | `currency`                   | Extract ISO 4217 currency codes from user input, handling declined forms, spellings without diacritics and currency symbols.                                                                                                | sk                                 |
| Decomposed birth number        | `birth_number_decomposition` | Decompose a Czech or Slovak birth number into year, month, and day components and indicate its validity.                                                                                                                    | cs, sk                             |
| Digit to word                  | `digit_to_word`              | Transcribe digits into readable numerals divided into groups up to 99.                                                                                                                                                      | cs, sk                             |
| No digits extractor            | `no_digits`                  | Return `True` when the customer's message contains no number – neither digits nor numbers written as words. Otherwise the result is empty.                                                                                  | any                                |
| Number pronunciation           | `pronounce_number`           | Return the number's digits separated by commas for slow pronunciation.                                                                                                                                                      | any                                |
| Parcel number extractor        | `parcel_number`              | Return all parcel numbers (e.g., '1518/3', '702/49') found in the user’s utterance.                                                                                                                                         | cs, sk                             |
| Random integer                 | `random_int`                 | Return a random integer between the specified start and stop values, with optional step and inclusive flag.                                                                                                                 | any                                |
| Simple number extractor        | `simple_number`              | Merge all digits from the user’s utterance into one continuous number string                                                                                                                                                | any                                |
| Simple number list extractor   | `simple_number_list`         | Extract numbers from the user’s utterance, merging space-separated digits into continuous numbers                                                                                                                           | any                                |
| Spell-out                      | `spell_out`                  | Spell out a string by separating each alphanumeric character with a comma and space                                                                                                                                         | cs, sk, pl, fr, de, nl             |
| Vehicle registration extractor | `registration_plate`         | Return the vehicle registration number from the user’s utterance for supported countries (cs, sk, pl, de, at, ch, ro, hu, en), with options for punctuation removal, spelling heuristics, transformations, and multi-match. | cs, sk, pl, de, at, ch, ro, hu, en |

## Advanced number

Technical name: `advanced_number`

Extract numbers from user input according to specified criteria, supporting grouping of digit sequences, leading zeros, and optional summing, pattern matching, and custom input.

| Parameter                      | Name           | Required | Default | Description                                                             |
| ------------------------------ | -------------- | -------- | ------- | ----------------------------------------------------------------------- |
| The smallest number of digits. | `min_digits`   | no       | `1`     | Minimum number of digits the extracted number must contain.             |
| The biggest number of digits.  | `max_digits`   | no       | `255`   | Maximum number of digits the extracted number can contain.              |
| Number matching regex pattern. | `pattern`      | no       |         | Optional regex; extracted number must match this pattern.               |
| Type of returned number.       | `return_type`  | no       | `str`   | Return the result as a string or integer.                               |
| Merging digits into one.       | `sum_numbers`  | no       | `False` | If true, join adjacent digit groups into a single number when possible. |
| Custom input                   | `custom_input` | no       |         | Use this text instead of the last user message for number extraction.   |

**Example input:** Order code is 0 2 3 4 5 6

**Example output:**

```
023456
```

## Amount extractor

Technical name: `amount`

Extract monetary amounts with their decimal part and pair each one with the currency standing next to it.

* Languages: sk.

| Parameter             | Name                    | Required | Default | Description                                                                 |
| --------------------- | ----------------------- | -------- | ------- | --------------------------------------------------------------------------- |
| Require currency      | `require_currency`      | no       | `False` | Return only amounts that have a currency next to them.                      |
| Max currency distance | `max_currency_distance` | no       | `30`    | How many characters away a currency may stand to be paired with the amount. |
| Get indices           | `get_indices`           | no       | `False` | When on, add the character start/end indices of each amount.                |
| Custom input          | `custom_input`          | no       |         | Provide text to extract amounts from instead of the last user message.      |

**Example input:** chcem zmenit 1 500,50 czk na eura

**Example output:**

```
[{'value': 1500.5, 'currency': 'CZK'}]
```

## Birth number

Technical name: `birth_number`

Extract and validate Czech, Slovak, Polish, and Romanian birth numbers from user input.

* Languages: cs, pl, sk, ro.

| Parameter    | Name           | Required | Default | Description                                                                        |
| ------------ | -------------- | -------- | ------- | ---------------------------------------------------------------------------------- |
| Custom input | `custom_input` | no       |         | Provide text to extract birth numbers from instead of using the last user message. |

**Example input:** The birth number is 736028/5163.

**Example output:**

```
['7360285163']
```

## Currency extractor

Technical name: `currency`

Extract ISO 4217 currency codes from user input, handling declined forms, spellings without diacritics and currency symbols.

* Languages: sk.

| Parameter         | Name            | Required | Default | Description                                                                                                   |
| ----------------- | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| Get indices       | `get_indices`   | no       | `False` | When on, return each code together with its character start/end indices.                                      |
| Allowed ISO codes | `allowed_codes` | no       |         | Keep only these ISO codes, e.g. the currencies on the current exchange rate list. Everything else is dropped. |
| Custom input      | `custom_input`  | no       |         | Provide text to extract currencies from instead of the last user message.                                     |

**Example input:** chcem zmenit 100 eur na dolare

**Example output:**

```
['EUR', 'USD']
```

## Decomposed birth number

Technical name: `birth_number_decomposition`

Decompose a Czech or Slovak birth number into year, month, and day components and indicate its validity.

* Languages: cs, sk.

| Parameter    | Name           | Required | Default | Description                                                                             |
| ------------ | -------------- | -------- | ------- | --------------------------------------------------------------------------------------- |
| Custom input | `custom_input` | no       |         | Provide a custom text containing a birth number instead of using the last user message. |

**Example input:** 736028/5163

**Example output:**

```
{'year': '1973', 'month': '10', 'day': '28', 'valid': 'True'}
```

## Digit to word

Technical name: `digit_to_word`

Transcribe digits into readable numerals divided into groups up to 99.

* Languages: cs, sk.

| Parameter    | Name           | Required | Default | Description                                                                                              |
| ------------ | -------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
| Digit        | `digit`        | yes      |         | Digit to be transcribed into words.                                                                      |
| Custom input | `custom_input` | no       |         | Custom input defined by the user from the flow. Here not used, instead mandatory digit argument is used. |

**Example input:** 8405913

**Example output:**

```
osemdesiat štyri, nula, päťdesiat deväť, trinásť
```

## No digits extractor

Technical name: `no_digits`

Return `True` when the customer's message contains no number – neither digits nor numbers written as words. Otherwise the result is empty.

| Parameter    | Name           | Required | Default | Description                                                             |
| ------------ | -------------- | -------- | ------- | ----------------------------------------------------------------------- |
| Custom input | `custom_input` | no       |         | Override the user’s utterance with a custom string to check for digits. |

**Example input:** I am Peter Bajaja.

**Example output:**

```
True
```

## Number pronunciation

Technical name: `pronounce_number`

Return the number's digits separated by commas for slow pronunciation.

* Can also be used in expressions as `pronounce_number()`.

| Parameter | Name     | Required | Default | Description                                          |
| --------- | -------- | -------- | ------- | ---------------------------------------------------- |
| Number    | `number` | yes      |         | Number to pronounce with digits separated by commas. |

**Example input:** This function does not use the user input utterance.

**Example output:**

```
1, 2, 3, 4
```

## Parcel number extractor

Technical name: `parcel_number`

Return all parcel numbers (e.g., '1518/3', '702/49') found in the user’s utterance.

* Languages: cs, sk.

| Parameter    | Name           | Required | Default | Description                                                                        |
| ------------ | -------------- | -------- | ------- | ---------------------------------------------------------------------------------- |
| Custom input | `custom_input` | no       |         | Override the user’s utterance with a custom string to extract parcel numbers from. |

**Example input:** My parcel number is 1518/3.

**Example output:**

```
['2161/20']
```

## Random integer

Technical name: `random_int`

Return a random integer between the specified start and stop values, with optional step and inclusive flag.

| Parameter | Name        | Required | Default | Description                                                       |
| --------- | ----------- | -------- | ------- | ----------------------------------------------------------------- |
| Start     | `start`     | yes      |         | Lower bound for the random integer (inclusive).                   |
| Stop      | `stop`      | yes      |         | Upper bound for the random integer (inclusive if inclusive=True). |
| Step      | `step`      | no       | `1`     | Increment step between possible values.                           |
| Inclusive | `inclusive` | no       | `True`  | When on, include the stop value in the range.                     |

**Example input:** This function does not use the user input utterance.

**Example output:**

```
42
```

## Simple number extractor

Technical name: `simple_number`

Merge all digits from the user’s utterance into one continuous number string

| Parameter    | Name           | Required | Default | Description                                |
| ------------ | -------------- | -------- | ------- | ------------------------------------------ |
| Custom input | `custom_input` | no       |         | Custom utterance text provided by the flow |

**Example input:** Hello 3 3 1 13, 23

**Example output:**

```
3311323
```

## Simple number list extractor

Technical name: `simple_number_list`

Extract numbers from the user’s utterance, merging space-separated digits into continuous numbers

| Parameter    | Name           | Required | Default | Description                                |
| ------------ | -------------- | -------- | ------- | ------------------------------------------ |
| Custom input | `custom_input` | no       |         | Custom utterance text provided by the flow |

**Example input:** Hello 3 3 1 13, 23

**Example output:**

```
['33113', '23']
```

## Spell-out

Technical name: `spell_out`

Spell out a string by separating each alphanumeric character with a comma and space

* Can also be used in expressions as `spell_out()`.
* Languages: cs, sk, pl, fr, de, nl.

| Parameter | Name     | Required | Default | Description              |
| --------- | -------- | -------- | ------- | ------------------------ |
| String    | `string` | yes      |         | Text string to spell out |

**Example input:** Hello 123

**Example output:**

```
H, e, l, l, o, 1, 2, 3
```

## Vehicle registration extractor

Technical name: `registration_plate`

Return the vehicle registration number from the user’s utterance for supported countries (cs, sk, pl, de, at, ch, ro, hu, en), with options for punctuation removal, spelling heuristics, transformations, and multi-match.

* Languages: cs, sk, pl, de, at, ch, ro, hu, en.

| Parameter           | Name                  | Required | Default | Description                                                                       |
| ------------------- | --------------------- | -------- | ------- | --------------------------------------------------------------------------------- |
| Remove punctuation  | `remove_punctuation`  | no       |         | When on, remove punctuation from the license plate before extraction.             |
| Countries           | `countries`           | no       |         | List of ISO country codes to check for registration formats (e.g., \['cs','sk']). |
| Custom input        | `custom_input`        | no       |         | Override the user’s utterance with a custom string to extract the plate from.     |
| Multi match         | `multi_match`         | no       | `False` | When on, return all matching plates instead of a single result.                   |
| Spelling heuristics | `spelling_heuristics` | no       | `False` | When on, apply spelling heuristics to interpret spelled-out letters.              |
| Transformations     | `transformation`      | no       | `True`  | List of transformations (e.g., words-to-numerals) to apply before extraction.     |

**Example input:** My car’s license plate is 4A2 3000.

**Example output:**

```
4A2-3000
```
