> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lexicons

> Create, retrieve, list and delete pronunciation lexicons for Plivo Text-to-Speech.

> [!NOTE]
>
> Save pronunciation rules once and reuse them by `lexicon_id` on any batch request or realtime reply.

A `Lexicon` object holds pronunciation rules for words such as brand names and acronyms. Pass its `lexicon_id` when you use [batch](https://plivo.com/docs/models/text-to-speech/api/batch.md) or open a [realtime](https://plivo.com/docs/models/text-to-speech/api/realtime.md) reply.

## The Lexicon Object

### Attributes

**lexicon\_id** `string`

Unique identifier for the lexicon. Starts with `lx_`.

**name** `string`

Your name for the lexicon. Up to 100 characters.

**kind** `string`

How every rule's `value` is written. Values: `ipa`, `arpa`, `respell`.

**rules** `array`

Up to 100 `{"word", "value"}` pairs. `word` is up to 100 characters, `value` up to 120.

**version** `integer`

Version of the lexicon.&#x20;

### Example Lexicon Object

```json theme={null}
{
  "lexicon_id": "lx_2bb70cb1eea545e08c83a98076802c8f",
  "name": "brands",
  "kind": "respell",
  "rules": [{"word": "Plivo", "value": "plee-voh"}],
  "version": 1
}
```

***

## Create a Lexicon

Create a lexicon. An organization can have up to 100.

```text theme={null}
POST https://api.plivo.com/v1/Account/{auth_id}/TTS/Lexicons/
```

### Arguments

**name** `string` *required*

Your name for the lexicon. Up to 100 characters.

**kind** `string` *required*

How the values are written. Values: `ipa`, `arpa`, `respell`.

**rules** `array` *required*

Up to 100 `{"word", "value"}` pairs.

```bash cURL theme={null}
curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/TTS/Lexicons/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"name": "brands", "kind": "respell", "rules": [{"word": "Plivo", "value": "plee-voh"}]}'
```

### Response

Returns the [Lexicon object](#the-lexicon-object), with the request's `api_id` and `"message": "created"`.

```json theme={null}
{
  "api_id": "148d6af0bee98c09",
  "lexicon_id": "lx_2bb70cb1eea545e08c83a98076802c8f",
  "name": "brands",
  "kind": "respell",
  "rules": [{"word": "Plivo", "value": "plee-voh"}],
  "version": 1,
  "message": "created"
}
```

***

## Retrieve a Lexicon

Get one lexicon by its ID.

```text theme={null}
GET https://api.plivo.com/v1/Account/{auth_id}/TTS/Lexicons/{lexicon_id}
```

### Arguments

No arguments required.

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/<auth_id>/TTS/Lexicons/<lexicon_id>" \
  -u '<auth_id>:<auth_token>'
```

### Response

Returns the [Lexicon object](#the-lexicon-object), with the request's `api_id`. Returns `404 not_found` if the lexicon doesn't exist.

***

## List All Lexicons

List every lexicon in your organization.

```text theme={null}
GET https://api.plivo.com/v1/Account/{auth_id}/TTS/Lexicons/
```

### Arguments

No arguments. Query parameters aren't accepted: one returns `422 invalid_request` naming it.

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/<auth_id>/TTS/Lexicons/" \
  -u '<auth_id>:<auth_token>'
```

### Response

**api\_id** `string`

Unique identifier for the request.

**meta** `object`

`limit`, `offset`, `total_count`, `next` and `previous`. All lexicons come back in one page.

**objects** `array`

Your [Lexicon objects](#the-lexicon-object).

```json theme={null}
{
  "api_id": "148d6af0bee98c09",
  "meta": {"limit": 1, "next": null, "offset": 0, "previous": null, "total_count": 1},
  "objects": [
    {
      "lexicon_id": "lx_2bb70cb1eea545e08c83a98076802c8f",
      "name": "brands",
      "kind": "respell",
      "rules": [{"word": "Plivo", "value": "plee-voh"}],
      "version": 1
    }
  ]
}
```

***

## Delete a Lexicon

Permanently delete a lexicon.

```text theme={null}
DELETE https://api.plivo.com/v1/Account/{auth_id}/TTS/Lexicons/{lexicon_id}
```

### Arguments

No arguments required.

```bash cURL theme={null}
curl -X DELETE "https://api.plivo.com/v1/Account/<auth_id>/TTS/Lexicons/<lexicon_id>" \
  -u '<auth_id>:<auth_token>'
```

### Response

Returns `200` on success. Returns `404 not_found` if the lexicon doesn't exist.

```json theme={null}
{"api_id": "148d6af0bee98c09", "lexicon_id": "lx_2bb70cb1eea545e08c83a98076802c8f", "message": "deleted"}
```

> [!NOTE]
>
> Synthesizing with a deleted `lexicon_id` returns `422 invalid_request` with `param: lexicon_id`.

## Related

* [Custom pronunciation](https://plivo.com/docs/models/text-to-speech/concepts/pronunciation.md)
