> For the complete documentation index, see [llms.txt](https://docs.wproofreader.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wproofreader.com/api-reference/user-custom-dictionary-api/actions/add-word-s-addword-addwords.md).

# Add word(s) (addword, addwords)

Add one or more words to a dictionary.

### Parameters

These parameters work with any `cmd`.

| Name           | Type    | Required   | Description                                                                                                                                                                        |
| -------------- | ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceid`    | string  | Cloud only | Cloud API key. Required for Cloud requests. Not used on-premises.                                                                                                                  |
| `format`       | string  | No         | Response format. Values: `json` (default), `xml`.                                                                                                                                  |
| `callback`     | string  | No         | JSONP wrapper function name. Use only with `format=json`.                                                                                                                          |
| `short_answer` | boolean | No         | <p>JSON only. When <code>true</code>, shortens JSON keys to reduce payload size.<br>See <a href="/pages/VXTsQ0sY5BFRLUsqxnbL#boolean-parameter-values">boolean parameters</a>.</p> |

See [Overview](/api-reference/overview.md#common-parameters) for details.

#### Command specific parameters

| Parameter  | Type   | Required | Default           | Notes                                                        |
| ---------- | ------ | -------- | ----------------- | ------------------------------------------------------------ |
| `cmd`      | string | Yes      | `user_dictionary` | Command name.                                                |
| `action`   | string | Yes      | `addwords`        | Use `addword` or `addwords`.                                 |
| `name`     | string | Yes      |                   | Dictionary name.                                             |
| `word`     | string | Yes\*    |                   | Single word to add.                                          |
| `wordlist` | string | Yes\*    |                   | Comma-separated list of words. Takes precedence over `word`. |

\* Provide `word` or `wordlist`.

### Behavior

* Adds a word or a wordlist.
* Ignores duplicates depending on deployment, or returns `WordAlreadyExistsException`.

{% hint style="info" %}
Auto-create behavior.

Some deployments create the dictionary automatically if `name` does not exist.
{% endhint %}

#### `wordlist` precedence

If `wordlist` is present and not empty, it overrides `word`.

### Response

Returns the words added in `wordlist`.

See [Response format](/api-reference/user-custom-dictionary-api/response-format.md).

### Errors

Common errors:

* Dictionary name is missing, invalid, or longer than 50 characters.
* No word was provided, or `wordlist` is empty.
* A word contains forbidden symbols.
* A word is longer than 63 characters.
* Word already exists in the dictionary.
  * Some deployments ignore duplicates instead of failing.

See [Errors reference](/api-reference/user-custom-dictionary-api/errors-reference.md).

### Examples

<details>

<summary>Add a single word</summary>

**Request body (JSON):**

```json
{
  "cmd": "user_dictionary",
  "action": "addwords",
  "name": "my_dict",
  "word": "DevOps"
}
```

**Response (JSON):**

```json
{
  "name": "my_dict",
  "action": "addword",
  "wordlist": ["DevOps"],
  "modificationTime": 1772124069
}
```

</details>

<details>

<summary>Add multiple words</summary>

**Request body (JSON):**

```json
{
  "cmd": "user_dictionary",
  "action": "addwords",
  "name": "my_dict",
  "wordlist": "API,SDK,DevOps"
}
```

**Response (JSON):**

```json
{
  "name": "my_dict",
  "action": "addword",
  "wordlist": ["API", "SDK", "DevOps"],
  "modificationTime": 1772124069
}
```

</details>