# Custom Dictionary, Dot Phrases & Text Replacements

Nabla offers three **user-level** personalization features that let a provider tailor API behavior to their vocabulary and workflow: the **Custom Dictionary**, **Dot Phrases**, and **Text Replacements**. They are complementary, but each one applies to a different workflow and at a different stage of the pipeline.

This guide explains what each feature does, when it applies, and how to choose the right one.

## Which one do I need?[​](#which-one-do-i-need "Direct link to Which one do I need?")

* The speech-to-text engine keeps **mishearing** a specialized term → add it to the **Custom Dictionary**.
* The provider wants a short trigger to expand into a structured block in their **generated note** → create a **Dot Phrase**.
* The provider wants a short trigger to expand into longer text while **dictating** → create a **Text Replacement**.

Custom Dictionary entries are complementary to the other two: because they improve *transcription accuracy*, adding the trigger of a Dot Phrase or Text Replacement to the Custom Dictionary can make that trigger more reliably detected in the first place.

## Recap Table[​](#recap-table "Direct link to Recap Table")

| Feature               | What it does                                             | Ambient workflow | Dictation workflow | When it is applied                                 |
| --------------------- | -------------------------------------------------------- | ---------------- | ------------------ | -------------------------------------------------- |
| **Custom Dictionary** | Improves speech-to-text accuracy for user-specific terms | ✅               | ✅                 | In **real time**, as the audio stream is processed |
| **Dot Phrases**       | Expands a spoken trigger into generated note content     | ✅               | ❌                 | **After transcription**, during note generation    |
| **Text Replacements** | Expands a dictated trigger into longer text              | ❌               | ✅                 | In **real time**, as the audio stream is processed |

In other words:

* **Custom Dictionary** improves the recognition of specific terms by the speech-to-text engine. It is used in both ambient and dictation workflows.
* **Dot Phrases** only affect note generation output.
* **Text Replacements** only affect dictation output.

## Custom Dictionary[​](#custom-dictionary "Direct link to Custom Dictionary")

A **Custom Dictionary Expression** improves the accuracy of the speech-to-text engine for terms that are not part of the default medical vocabulary. For example: organization names, local procedures, or uncommon acronyms that the engine tends to mishear.

It is a **recognition-time hint**, not a text substitution. You provide the correct spelling of a word or expression, and it biases the speech-to-text pipeline toward transcribing it that way when it hears something similar.

🗒️

**Example:** If the provider often mentions `Xeljanz`, but the transcript sometimes renders it incorrectly, adding `Xeljanz` to the Custom Dictionary can improve recognition in both ambient and dictation workflows.

Each expression carries:

| Field           | Description                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `expression`    | The term to recognize more reliably (1–64 characters), e.g. `metformin`. |
| `speech_locale` | The locale the expression should be recognized in.                       |

The Custom Dictionary is used in both ambient and dictation workflows. It affects the [Transcription WebSocket](/2026-07-01/user/transcribe-ws.md), the [Dictation WebSocket](/user/dictate-ws.md), and their REST equivalents.

**Manage Custom Dictionary:**

* [Get all Custom Dictionary Expressions](/2026-07-01/user/get-user-custom-dictionary-expressions.md)
* [Get a Custom Dictionary Expression](/2026-07-01/user/get-user-custom-dictionary-expression.md)
* [Create a Custom Dictionary Expression](/2026-07-01/user/create-user-custom-dictionary-expression.md)
* [Update a Custom Dictionary Expression](/2026-07-01/user/update-user-custom-dictionary-expression.md)
* [Delete a Custom Dictionary Expression](/2026-07-01/user/delete-user-custom-dictionary-expression.md)

## Dot Phrases[​](#dot-phrases "Direct link to Dot Phrases")

A **Dot Phrase** is a concise trigger that expands into a predefined block of text inside a **generated clinical note**. Dot Phrases are specific to the **ambient** workflow and are matched *after* the encounter is transcribed, **during note generation**.

🗒️

**Example:** If the transcript contains the trigger *"Your physical exam is normal"*, Nabla can return a suggested Dot Phrase containing a reusable normal physical exam block such as:

> * Heart Examination: Normal, with regular rate and rhythm, no murmurs.
> * Lung Assessment: Normal breath sounds, no wheezes, crackles, or rhonchi.
> * Abdominal Evaluation: Normal, no tenderness, masses, or hepatosplenomegaly.

The integration can then insert that block into the appropriate section of the generated note.

Each Dot Phrase carries:

| Field                         | Description                                                                                                     |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `title`                       | A user-friendly label. Does not affect matching.                                                                |
| `trigger`                     | The phrase that, if detected in the transcript, prompts this Dot Phrase, e.g. *"Your physical exam is normal"*. |
| `replacement`                 | The block of text to insert when the trigger is matched, e.g. the normal physical exam block shown above.       |
| `content_auto_update_enabled` | If `true`, the inserted text is dynamically adapted to the encounter instead of used verbatim.                  |

When you call one of the note-generation endpoints, user Dot Phrases are matched against the transcript and matching entries are returned in the response as `suggested_dot_phrases`.

Each suggestion includes the `text_to_insert` and, where possible, the note section it belongs to. When `content_auto_update_enabled` is on, `text_to_insert` may differ from the raw `replacement`: it is adapted to the encounter discussion (for instance to include exceptions) instead of being used verbatim.

In both cases, the generated note itself never includes the Dot Phrase content automatically: Nabla only suggests it, and the integration is responsible for inserting `text_to_insert` into the appropriate place in the note.

**Manage Dot Phrases:**

* [Get all Dot Phrases](/2026-07-01/user/get-user-dot-phrases.md)
* [Get a Dot Phrase](/2026-07-01/user/get-user-dot-phrase.md)
* [Create a Dot Phrase](/2026-07-01/user/create-user-dot-phrase.md)
* [Update a Dot Phrase](/2026-07-01/user/update-user-dot-phrase.md)
* [Delete a Dot Phrase](/2026-07-01/user/delete-user-dot-phrase.md)
* Bulk operations: [create](/2026-07-01/user/bulk-create-user-dot-phrases.md), [update](/user/bulk-update-user-dot-phrases.md), [delete](/user/bulk-delete-user-dot-phrases.md)

## Text Replacements[​](#text-replacements "Direct link to Text Replacements")

A **Text Replacement** is the dictation equivalent of a Dot Phrase: a concise trigger that expands into a longer piece of text. It is specific to **dictation** and is applied **in real time** as the dictation stream is processed. As soon as the trigger phrase is detected, the transcribed output is automatically replaced with the replacement text.

🗒️

**Example:** If the provider dictates *"normal blood pressure"*, a Text Replacement can replace that trigger with *"Blood pressure is within normal limits."* in the dictation output.

Each Text Replacement carries:

| Field         | Description                                                                  |
| ------------- | ---------------------------------------------------------------------------- |
| `trigger`     | The dictated phrase that will be replaced, e.g. *"Normal blood pressure"*.   |
| `replacement` | The text substituted into the dictation result when the trigger is detected. |

Text Replacements apply to both the [Dictation WebSocket](/2026-07-01/user/dictate-ws.md) and the [REST dictation endpoints](/user/dictate.md).

**Manage Text Replacements:**

* [Get all Text Replacements](/2026-07-01/user/get-user-text-replacements.md)
* [Get a Text Replacement](/2026-07-01/user/get-user-text-replacement.md)
* [Create a Text Replacement](/2026-07-01/user/create-user-text-replacement.md)
* [Update a Text Replacement](/2026-07-01/user/update-user-text-replacement.md)
* [Delete a Text Replacement](/2026-07-01/user/delete-user-text-replacement.md)