> 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/v6.12.0/api-reference/custom-dictionary-api/getting-started.md).

# Getting started

This is the fastest end-to-end flow:

1. `create` a dictionary.
2. `addwords` to seed the wordlist.
3. `getwords` to verify.
4. `getdicts` to list dictionaries and states.

If you’re new to this API, read [Overview](/v6.12.0/api-reference/custom-dictionary-api/overview.md) first.

{% stepper %}
{% step %}

#### 1) Create a dictionary

Use [create](/v6.12.0/api-reference/custom-dictionary-api/actions/create-dictionary-create.md) to create a new dictionary.

Required: `lang`, `description`.

{% hint style="info" %}
Save the `id` from the response.

You need it for all follow-up requests.
{% endhint %}

Example (JSON):

```json
{
    "cmd": "custom_dictionary",
    "access_key": "...",
    "lang": "en_US",
    "action": "create",
    "description": "My first dictionary"
}
```

Example response (JSON):

```json
{
  "result": [
    {
      "id": 101565,
      "lang": "en_US",
      "description": "My first dictionary",
      "wordlist": [],
      "status": "success",
      "message": ["Dictionary created."]
    }
  ]
}
```

{% endstep %}

{% step %}

#### 2) Add initial words

Use [addwords](/v6.12.0/api-reference/custom-dictionary-api/actions/add-list-of-words-addwords.md) to add a wordlist to existing dictionary.

Required: `id`, `wordlist`.

```json
{
    "cmd": "custom_dictionary",
    "access_key": "...",
    "lang": "en_US",
    "action": "addwords",
    "id": 101565,
    "wordlist": "word1,word2"
}
```

Example response:

```json
{
  "result": [
    {
      "id": 101565,
      "lang": "en_US",
      "description": "My first dictionary",
      "wordlist": ["word1", "word2"],
      "status": "success",
      "message": ["Words added."]
    }
  ]
}
```

{% endstep %}

{% step %}

#### 3) Verify words

Use [getwords](/v6.12.0/api-reference/custom-dictionary-api/actions/get-words-from-dictionary-getwords.md) to fetch the full wordlist.

```json
{
    "cmd": "custom_dictionary",
    "access_key": "...",
    "action": "getwords",
    "id": 101565
}
```

Example response:

```json
{
  "result": [
    {
      "id": 101565,
      "lang": "en_US",
      "description": "My first dictionary",
      "wordlist": ["word1", "word2"],
      "count": 3,
      "status": "success",
      "message": ["Wordlist extracted."]
    }
  ]
}
```

{% endstep %}

{% step %}

#### 4) List dictionaries

Use [getdicts](/v6.12.0/api-reference/custom-dictionary-api/actions/list-dictionaries-getdicts.md) to list dictionaries and their state.

```json
{
    "cmd": "custom_dictionary",
    "access_key": "...",
    "action": "getdicts",
    "id": 101565
}
```

Example response:

```json
{
  "result": [
    {
      "id": 101565,
      "lang": "en_US",
      "description": "My first dictionary",
      "count": 2,
      "state": true,
      "status": "success",
      "message": ["Dictionaries extracted."]
    }
  ]
}
```

{% hint style="info" %}
`getdicts` does not include `wordlist`.

Use `getwords` for the actual words.
{% endhint %}
{% endstep %}
{% endstepper %}

### Next

* Learn each operation in [Actions](/v6.12.0/api-reference/custom-dictionary-api/actions.md).
* See the full list of fields in [Response format](/v6.12.0/api-reference/custom-dictionary-api/response-format.md).
* Troubleshoot failures in [Errors reference](/v6.12.0/api-reference/custom-dictionary-api/errors-reference.md).