# Import words into a vocabulary list

Add and update words from an `.xlsx` or `.csv` file of up to 5 MB and 10,000 rows. A word already in the list (same written form and language, ignoring case) is updated; nothing is ever deleted. Send `dry_run` to check a file without writing. Needs edit rights on the list. A file that would take the list past its limit writes nothing.

#### Path Parameters

**`list_id`** string required

The list to import into.

#### Request Body

Send `multipart/form-data`.

**`file`** file required

The `.xlsx` or `.csv` file. The first row names the columns: `written` (required), `sounds_like` (several separated by `;`), `language`, `kind`, `weight` and `enabled`. A column left out keeps the stored value. A `.csv` may use `,` or `;` and may start with a byte-order mark.

**`dry_run`** boolean optional · Defaults to `false`

Check the file without writing.

## Returns

**`dry_run`** boolean

True when nothing was written.

**`created`** integer

Words added to the list.

**`updated`** integer

Words of the list that were changed.

**`unchanged`** integer

Words already in the list as given.

**`errors`** integer

Rows skipped because of an error.

**`rows`** array

The first 500 rows that are not unchanged: `row` (counting the header as row 1), `status` (`created`, `updated` or `error`), `written`, and `error` — one of `written_missing`, `written_too_long`, `language_invalid`, `kind_invalid`, `weight_invalid`, `replace_needs_sounds_like`, `too_many_sounds_like`, `sounds_like_too_long` or `duplicate_in_file`.

Example

```bash cURL
curl -X POST "https://api.aitronos.com/v1/vocabulary/lists/voclist_8f2a61c4e0b94d7a/import" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -F "file=@words.csv" \
  -F "dry_run=true"
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

with open("words.csv", "rb") as file:
    response = requests.post(
        "https://api.aitronos.com/v1/vocabulary/lists/voclist_8f2a61c4e0b94d7a/import",
        headers={"X-API-Key": api_key},
        files={"file": ("words.csv", file, "text/csv")},
        data={"dry_run": "true"},
    )

print(response.json())
```


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

const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('dry_run', 'true');

const response = await fetch('https://api.aitronos.com/v1/vocabulary/lists/voclist_8f2a61c4e0b94d7a/import', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});

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

**Response:**


```json 200 OK
{
  "dry_run": true,
  "created": 41,
  "updated": 3,
  "unchanged": 112,
  "errors": 1,
  "rows": [
    {
      "row": 7,
      "status": "updated",
      "written": "Kubernetes",
      "error": null
    },
    {
      "row": 12,
      "status": "error",
      "written": null,
      "error": "written_missing"
    }
  ]
}
```

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": "VOCABULARY_LIST_NOT_FOUND",
    "message": "The vocabulary list was not found.",
    "system_message": "Vocabulary list 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": "DICTIONARY_LIMIT_REACHED",
    "message": "The vocabulary limit of 5000 entries is reached.",
    "system_message": "Vocabulary list entry limit reached.",
    "type": "client_error",
    "status": 409,
    "details": {
      "limit": 5000,
      "current_count": 4990
    },
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```


```json 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "VOCABULARY_IMPORT_INVALID",
    "message": "The vocabulary file cannot be imported.",
    "system_message": "Vocabulary import refused.",
    "type": "validation_error",
    "status": 422,
    "details": {
      "reason": "missing_written_column"
    },
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```

## Related Resources

- [Export a vocabulary list](/api-reference/vocabulary/export-a-vocabulary-list) — Download a list in the same format.
- [Vocabulary API](/api-reference/vocabulary/_index) — Overview of lists, entries and settings.