> 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/api-documentation/dictionaries-api/how-to-import-dictionary-csv.md).

# How to Import Dictionary CSV

### How it works

1. Upload the CSV file with the TUS client.
2. Read the `Task` response header.
3. Use that value as `taskUuid` in the confirmation request.

### Step 1. Upload the CSV file

Use the `/api/v1/upload/dictionary-large` endpoint with a TUS client such as [tus-js-client](https://github.com/tus/tus-js-client).

**Required headers**

* `Dictionary` — target dictionary UUID
* `Mailbox` — mailbox UUID
* `Authorization` — bearer token

After a successful upload, read the `Task` response header. Use this value as `taskUuid` in the next step.

```javascript
input.addEventListener("change", function (e) {
    var file = e.target.files[0];

    new tus.Upload(file, {
        endpoint: "http://localhost:8080/api/v1/upload/dictionary-large",
        retryDelays: [0, 3000, 5000, 10000, 20000],
        metadata: {
            filename: file.name,
            filetype: file.type
        },
        headers: {
            Dictionary: dictionaryUuid,
            Mailbox: mailboxUuid,
            Authorization: "Bearer ..."
        },
        onError: function (error) {
            console.log("Failed because: " + error);
        },
        onProgress: function (bytesUploaded, bytesTotal) {
            var percentage = (bytesUploaded / bytesTotal * 100).toFixed(2);
            console.log(bytesUploaded, bytesTotal, percentage + "%");
        },
        onSuccess: function () {
            console.log("Download %s from %s", upload.file.name, upload.url);
        },
        onAfterResponse: async (req, res) => {
            if (res.getHeader("Task")) {
                taskUuid = res.getHeader("Task");
            }
        }
    }).start();
});
```

### Step 2. Confirm the import task

Use the `/api/v1/upload/{taskUuid}/confirm` endpoint to confirm the uploaded CSV import.

Replace `{taskUuid}` with the value from the `Task` response header.

**Confirmation parameters**

* `headerFirstRow` — Set `true` if the first CSV row contains column names.
* `replace` — Set `true` to remove existing dictionary records before import.

```json
{
  "headerFirstRow": true,
  "replace": false
}
```

### CSV requirements

* Upload a `.csv` file
* Set `headerFirstRow` according to your file structure

### Related topics

* [Dictionaries API](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/dictionaries-api)
* [Dictionary Field API](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/template-api/template-dynamic-fields-api/dictionary-field-api)
* [Swagger UI](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/swagger-ui)