# Approve a vocabulary suggestion

Write the suggested word into a list and mark the suggestion approved. The word goes to the organization's target list unless `list_id` names another; the caller needs edit rights on that list. A word already in the list answers `DICTIONARY_TERM_DUPLICATE` and the suggestion stays pending. Needs the right to manage the team vocabulary.

#### Path Parameters

**`suggestion_id`** string required

The suggestion ID.

#### Request Body

Every field is optional; send `{}` to write the suggestion as it is.

**`list_id`** string optional

The list to write into; null for the organization's target list.

**`written`** string optional

How to write the word, 1 to 100 characters; the suggested term when null.

**`sounds_like`** array of strings optional

Up to 10 spoken forms; the suggestion's own when null.

**`language`** string optional

The language tag; the suggestion's own when null.

**`kind`** string optional · Defaults to `bias`

`bias` makes the word more likely to be recognized; `replace` also rewrites each spoken form to the written form.

## Returns

**`suggestion`** object

The decided suggestion, with the fields of [List vocabulary suggestions](/api-reference/vocabulary/list-vocabulary-suggestions).

**`entry`** object or null

The entry an approval wrote, as returned by [Get a vocabulary entry](/api-reference/vocabulary/get-a-vocabulary-entry); null on dismiss.

Example

```bash cURL
curl -X POST "https://api.aitronos.com/v1/vocabulary/suggestions/vsug_4e8b2d6f1a3c5097/approve" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sounds_like": ["cube ernetes"]}'
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/vocabulary/suggestions/vsug_4e8b2d6f1a3c5097/approve",
    headers={"X-API-Key": api_key},
    json={"sounds_like": ["cube ernetes"]},
)

print(response.json())
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/vocabulary/suggestions/vsug_4e8b2d6f1a3c5097/approve', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"sounds_like": ["cube ernetes"]})
});

const data = await response.json();
console.log(data);
```

**Response:**


```json 200 OK
{
  "suggestion": {
    "id": "vsug_4e8b2d6f1a3c5097",
    "term": "Kubernetes",
    "language": null,
    "source": "learned",
    "people_count": 4,
    "sounds_like": [
      "cube ernetes"
    ],
    "state": "approved",
    "decided_by_user_id": "usr_3c91d0a2b7e4",
    "decided_at": "2026-10-26T09:30:00Z",
    "list_id": "voclist_1b7d5e9f3a2c4680",
    "entry_id": "tdict_5a9c2e7b1d3f4068",
    "refreshed_at": "2026-10-26T09:30:00Z"
  },
  "entry": {
    "id": "tdict_5a9c2e7b1d3f4068",
    "scope": "list",
    "list_id": "voclist_1b7d5e9f3a2c4680",
    "written": "Kubernetes",
    "sounds_like": [
      "cube ernetes"
    ],
    "language": null,
    "kind": "bias",
    "source": "suggested",
    "weight": 1.0,
    "enabled": true,
    "visibility": "list",
    "shared": false,
    "owner_user_id": "usr_3c91d0a2b7e4",
    "reached_through": "owner",
    "can_edit": true,
    "can_share": true,
    "stats": {
      "applied_count": 0,
      "heard_count": 0,
      "corrected_count": 0,
      "last_applied_at": null,
      "last_heard_at": null
    },
    "created_at": "2026-10-26T09:30:00Z",
    "updated_at": "2026-10-26T09:30:00Z"
  }
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to perform this action.",
    "system_message": "Caller lacks the rights this operation needs.",
    "type": "authorization_error",
    "status": 403,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "SUGGESTION_NOT_FOUND",
    "message": "This vocabulary suggestion does not exist.",
    "system_message": "Vocabulary suggestion not found.",
    "type": "client_error",
    "status": 404,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```


```json 409 Conflict
{
  "success": false,
  "error": {
    "code": "VOCABULARY_SUGGESTION_DECIDED",
    "message": "This vocabulary suggestion was already decided.",
    "system_message": "Vocabulary suggestion already decided.",
    "type": "client_error",
    "status": 409,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```


```json 409 Conflict
{
  "success": false,
  "error": {
    "code": "DICTIONARY_TERM_DUPLICATE",
    "message": "This word is already in the list.",
    "system_message": "Duplicate vocabulary entry.",
    "type": "client_error",
    "status": 409,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```


```json 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "VOCABULARY_ENTRY_INVALID",
    "message": "The vocabulary entry is not valid.",
    "system_message": "Invalid vocabulary entry.",
    "type": "validation_error",
    "status": 422,
    "details": {
      "reason": "replace_needs_sounds_like"
    },
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```

## Related Resources

- [Dismiss a vocabulary suggestion](/api-reference/vocabulary/dismiss-a-vocabulary-suggestion) — Never suggest the word again.
- [Approve or dismiss vocabulary suggestions in bulk](/api-reference/vocabulary/approve-or-dismiss-vocabulary-suggestions-in-bulk) — Decide up to 100 at once.
- [Vocabulary API](/api-reference/vocabulary/_index) — Overview of lists, entries and settings.