---
title: "Create a pronunciation dictionary"
method: POST
path: "/pronunciation_dicts"
tags: ["Pronunciation Dictionaries"]
---

# Create a pronunciation dictionary

`POST /pronunciation_dicts`

Create a new pronunciation dictionary for the authenticated organization. Each dictionary contains a list of items that control how specific words are spoken. Items can be alias type (text replacement) or phoneme type (IPA pronunciation notation).

As an alternative to providing items directly as JSON, you can upload a dictionary file (PLS/XML or plain text format, max 1MB) using multipart/form-data. PLS files use the standard W3C Pronunciation Lexicon Specification XML format. Text files use a line-based format: `word=alias` for aliases, `word:/phoneme/` for IPA phonemes.

Limits:
- Maximum 50 dictionaries per organization
- Maximum 100 items per dictionary
- Text: max 200 characters
- Alias/phoneme value: max 500 characters
- File upload: max 1MB (1,048,576 bytes)

## Request body

- CreatePronunciationDictRequest — Request body for creating a pronunciation dictionary.
  - `name` string, required — Human-readable name. Must be unique within the organization.
  - `items` PronunciationDictItem[], required — List of pronunciation items (alias or phoneme type). At least one item is required.
    - union — A single pronunciation dictionary item. Use type 'alias' to replace matched text with a spoken alias, or type 'phoneme' to specify exact pronunciation using IPA notation.
      - PronunciationDictAliasItem — An alias pronunciation item. When the `text` value is found in input, it is replaced with the `alias` before speech synthesis.
        - `text` string, required — The text to match in the input. Case-insensitive matching is used during synthesis.
        - `type` 'alias', required — The item type.
        - `alias` string, required — The replacement text that will be spoken instead.
      - PronunciationDictPhonemeItem — A phoneme pronunciation item. When the `text` value is found in input, it is pronounced using the specified IPA phoneme notation.
        - `text` string, required — The text to match in the input. Case-insensitive matching is used during synthesis.
        - `type` 'phoneme', required — The item type.
        - `phoneme` string, required — The phoneme notation representing the desired pronunciation.
        - `alphabet` 'ipa', required — The phonetic alphabet used for the phoneme notation.

## Response `201`

Pronunciation dictionary created successfully.

- PronunciationDictResponse — Response containing a single pronunciation dictionary.
  - `data` PronunciationDictData — A pronunciation dictionary record.
    - `record_type` 'pronunciation_dict' — Identifies the resource type.
    - `id` string, uuid — Unique identifier for the pronunciation dictionary.
    - `name` string — Human-readable name for the dictionary. Must be unique within the organization.
    - `items` PronunciationDictItem[] — List of pronunciation items (alias or phoneme type).
      - union — A single pronunciation dictionary item. Use type 'alias' to replace matched text with a spoken alias, or type 'phoneme' to specify exact pronunciation using IPA notation.
        - PronunciationDictAliasItem — An alias pronunciation item. When the `text` value is found in input, it is replaced with the `alias` before speech synthesis.
          - `text` string, required — The text to match in the input. Case-insensitive matching is used during synthesis.
          - `type` 'alias', required — The item type.
          - `alias` string, required — The replacement text that will be spoken instead.
        - PronunciationDictPhonemeItem — A phoneme pronunciation item. When the `text` value is found in input, it is pronounced using the specified IPA phoneme notation.
          - `text` string, required — The text to match in the input. Case-insensitive matching is used during synthesis.
          - `type` 'phoneme', required — The item type.
          - `phoneme` string, required — The phoneme notation representing the desired pronunciation.
          - `alphabet` 'ipa', required — The phonetic alphabet used for the phoneme notation.
    - `version` integer — Auto-incrementing version number. Increases by 1 on each update. Used for optimistic concurrency control and cache invalidation.
    - `created_at` string, date-time — ISO 8601 timestamp with millisecond precision.
    - `updated_at` string, date-time — ISO 8601 timestamp with millisecond precision.

## Other responses

- `401` — Unauthorized. Invalid or missing API key.
- `422` — Validation error or organization limit exceeded.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api/revisions/e32d46c5945b/schema)