> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/guides/import-dictionary-csv.md).

# Import Dictionary CSV

This document explains how to import a dictionary CSV file, including the upload step and the import confirmation request.

### Step 1 Upload the CSV file

```http
POST /api/v1/upload/dictionary/{dictionaryUuid}
Authorization: Bearer {token}
Mailbox: {mailboxUuid}
Content-Type: multipart/form-data
```

<table><thead><tr><th width="147">Parameter</th><th width="120">Location</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>dictionaryUuid</code></td><td>Path</td><td>Yes</td><td>UUID of the target dictionary</td></tr><tr><td><code>Mailbox</code></td><td>Header</td><td>Yes</td><td>Current mailbox UUID</td></tr><tr><td><code>file</code></td><td>Form data</td><td>Yes</td><td>CSV file to import</td></tr></tbody></table>

```bash
curl --request POST \
  --url "https://api.docstudio.com/api/v1/upload/dictionary/{dictionaryUuid}" \
  --header "Authorization: Bearer {token}" \
  --header "Mailbox: {mailboxUuid}" \
  --form "file=@dictionary.csv"
```

The endpoint returns `201 Created`:

```json
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

Response fields:

| Field  | Type | Description            |
| ------ | ---- | ---------------------- |
| `uuid` | UUID | Upload task identifier |

Use `uuid` as `uploadUuid` in the confirmation and status requests.

Status codes:

| Status code   | Description                    |
| ------------- | ------------------------------ |
| `201 Created` | CSV file uploaded successfully |

### Step 2 Confirm the import

```http
PUT /api/v1/upload/{uploadUuid}/confirm
Authorization: Bearer {token}
Content-Type: application/json
```

Path parameters:

| Parameter    | Type | Required | Description            |
| ------------ | ---- | -------- | ---------------------- |
| `uploadUuid` | UUID | Yes      | Upload task identifier |

Request body:

```json
{
  "headerFirstRow": true,
  "delimiter": ",",
  "quote": "\"",
  "escape": "\\",
  "replace": false
}
```

<table><thead><tr><th width="151">Field</th><th width="102">Type</th><th width="106">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>headerFirstRow</code></td><td>boolean</td><td>Yes</td><td>Indicates whether the first row contains column names</td></tr><tr><td><code>delimiter</code></td><td>string</td><td>Yes</td><td>CSV column delimiter</td></tr><tr><td><code>quote</code></td><td>string</td><td>Yes</td><td>CSV quote character</td></tr><tr><td><code>escape</code></td><td>string</td><td>Yes</td><td>CSV escape character</td></tr><tr><td><code>replace</code></td><td>boolean</td><td>Yes</td><td>Removes existing dictionary records before import</td></tr></tbody></table>

Set `headerFirstRow` to `true` when the first CSV row contains column names. Set `replace` to `true` to remove existing records before the import.

### Step 3 Check the import status

```http
GET /api/v1/upload/{uploadUuid}
Authorization: Bearer {token}
```

Path parameters:

| Parameter    | Type | Required | Description            |
| ------------ | ---- | -------- | ---------------------- |
| `uploadUuid` | UUID | Yes      | Upload task identifier |

Response example:

```json
{
  "status": "PROCESSING",
  "createdAt": "2026-08-27T13:11:11.912Z",
  "errorMessage": null
}
```

Response fields:

| Field          | Type           | Description                |
| -------------- | -------------- | -------------------------- |
| `status`       | string         | Current import task status |
| `createdAt`    | datetime       | Task creation time         |
| `errorMessage` | string or null | Import error message       |

Check the task until `status` becomes `COMPLETED`. If it becomes `FAILED`, review `errorMessage`.

### Related topics

* [Dictionaries](/api-reference/dictionaries.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)