> 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-reference/dictionaries.md).

# Dictionaries

This document contains dictionary endpoints, including parameters, request bodies, responses, and status codes.

## Dictionaries

Dictionaries store structured, reusable data that can be shared across DocStudio templates and envelopes. They are useful for centrally managed datasets such as employees, vendors, products, cost centers, office locations, contract types, or other values that should remain consistent across multiple document workflows.

A dictionary contains columns that define its structure and records that contain its data. Dictionary fields can display selectable values from a dictionary, while related values from the selected record can be used by lookup logic. For complete request and response schemas, parameter requirements, and status codes, use the [Swagger UI](https://api.docstudio.com/swagger-ui/index.html).

### Business goals

Dictionary endpoints support the following business goals:

* **Centralize reusable business data.** Store reference data once and reuse it across templates, envelopes, and document workflows.
* **Synchronize DocStudio with external systems.** Create, update, search, or delete dictionary records when data changes in an ERP, CRM, HR, or another internal system.
* **Provide controlled values for document fields.** Retrieve valid options for Dictionary fields and use related record values when filling documents.
* **Manage dictionary structure.** Create and update the columns that define the data stored in each record.
* **Export dictionary data.** Generate a CSV export for reporting, backup, migration, or external processing.

### Endpoint summary

#### Dictionary lifecycle

<table><thead><tr><th width="98">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/v1/dictionary</code></td><td>Retrieve available dictionaries or find one by name, UUID, or access level</td></tr><tr><td><code>POST</code></td><td><code>/api/v1/dictionary</code></td><td>Create an empty dictionary and receive its UUID</td></tr><tr><td><code>GET</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}</code></td><td>Retrieve a dictionary and optionally include its columns and record count</td></tr><tr><td><code>PATCH</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}</code></td><td>Set or update the dictionary name, description, access level, or filtered-access setting</td></tr><tr><td><code>PATCH</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/archive</code></td><td>Archive a dictionary that is no longer used for new data</td></tr><tr><td><code>GET</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/check</code></td><td>Check whether the dictionary exists and is accessible in the current context</td></tr></tbody></table>

#### Dictionary columns

<table><thead><tr><th width="98">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>POST</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/column</code></td><td>Add a column that defines part of the dictionary record structure</td></tr><tr><td><code>PUT</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/column/{columnUuid}</code></td><td>Change a column name, order, width, or long-text setting</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/column/{columnUuid}</code></td><td>Remove a column that is no longer required</td></tr><tr><td><code>GET</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/column/{columnUuid}/check</code></td><td>Check whether a column exists and is accessible</td></tr><tr><td><code>POST</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/column/{columnUuid}</code></td><td>Retrieve selectable values from a column for a Dictionary field</td></tr></tbody></table>

#### Dictionary records

<table><thead><tr><th width="98">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>POST</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/records</code></td><td>Retrieve records and filter them by column values</td></tr><tr><td><code>POST</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/record</code></td><td>Create one or multiple dictionary records</td></tr><tr><td><code>GET</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/record/{recordUuid}</code></td><td>Retrieve all values stored in one record</td></tr><tr><td><code>PATCH</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/record/{recordUuid}</code></td><td>Update selected column values in an existing record</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/record</code></td><td>Delete one or multiple records</td></tr><tr><td><code>POST</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/record-uuids</code></td><td>Find record UUIDs by values stored in a specific column</td></tr><tr><td><code>GET</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/record/{recordUuid}/column/{columnUuid}</code></td><td>Retrieve one column value from a specific record</td></tr></tbody></table>

#### Dictionary export

<table><thead><tr><th width="98">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>POST</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/download</code></td><td>Start an asynchronous dictionary export in CSV format</td></tr><tr><td><code>GET</code></td><td><code>/api/v1/dictionary/{dictionaryUuid}/download/status/{taskUuid}</code></td><td>Check the export task and retrieve the generated file URL when it is ready</td></tr></tbody></table>

### Dictionary structure and headers

Most dictionary operations require the current mailbox UUID in the `Mailbox` header. The mailbox context determines which dictionaries and records are available to the request.

```http
Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {mailboxUuid}
```

Create a dictionary as an empty object. Save its `dictionaryUuid`. Then update its properties, add columns, and create records.

Save each `columnUuid`. Use it in record requests to identify the column for each value.

```json
{
  "uuid": "{columnUuid}",
  "value": "Acme Corporation"
}
```

To create multiple records, send an array of records. Each record is represented by an array of column-value objects.

```json
[
  [
    {
      "uuid": "{vendorCodeColumnUuid}",
      "value": "V-1001"
    },
    {
      "uuid": "{vendorNameColumnUuid}",
      "value": "Acme Corporation"
    }
  ],
  [
    {
      "uuid": "{vendorCodeColumnUuid}",
      "value": "V-1002"
    },
    {
      "uuid": "{vendorNameColumnUuid}",
      "value": "Northwind Logistics"
    }
  ]
]
```

Start an export with `POST /api/v1/dictionary/{dictionaryUuid}/download`. Save the returned `taskUuid`. Use `GET /api/v1/dictionary/{dictionaryUuid}/download/status/{taskUuid}` to check the task and retrieve the generated file URL.

### Practical example: Synchronize a vendor directory

A company stores its approved vendors in an ERP system and wants the same data to be available in DocStudio document workflows. The integration creates a Vendor Directory dictionary, defines its columns, adds vendor records, and searches those records when business data is updated.

#### Create an empty dictionary

```http
POST /api/v1/dictionary
Authorization: Bearer {token}
Mailbox: {mailboxUuid}
```

The response contains the new `dictionaryUuid`.

```json
{
  "uuid": "{dictionaryUuid}"
}
```

#### Configure the dictionary

```http
PATCH /api/v1/dictionary/{dictionaryUuid}
Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {mailboxUuid}

{
  "name": "Vendor Directory",
  "description": "Approved vendors synchronized from the ERP system",
  "access": "mailbox",
  "filteredAccessOnly": false
}
```

#### Create the columns

Create each column with the following values. Save every returned column UUID. Record requests use UUIDs instead of column names.

<table data-header-hidden><thead><tr><th width="140"></th><th width="184"></th><th width="195"></th><th></th></tr></thead><tbody><tr><td>Column</td><td><code>name</code></td><td><code>order</code></td><td><code>width</code></td></tr><tr><td>vendor code</td><td><code>Vendor Code</code></td><td><code>0</code></td><td><code>150</code></td></tr><tr><td>vendor name</td><td><code>Vendor Name</code></td><td><code>1</code></td><td><code>300</code></td></tr><tr><td>country</td><td><code>Country</code></td><td><code>2</code></td><td><code>150</code></td></tr></tbody></table>

```http
POST /api/v1/dictionary/{dictionaryUuid}/column
Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {mailboxUuid}

{
  "name": "Vendor Code",
  "order": 0,
  "width": 150,
  "longText": false
}
```

#### Create vendor records

```http
POST /api/v1/dictionary/{dictionaryUuid}/record
Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {mailboxUuid}

[
  [
    {
      "uuid": "{vendorCodeColumnUuid}",
      "value": "V-1001"
    },
    {
      "uuid": "{vendorNameColumnUuid}",
      "value": "Acme Corporation"
    },
    {
      "uuid": "{countryColumnUuid}",
      "value": "United States"
    }
  ],
  [
    {
      "uuid": "{vendorCodeColumnUuid}",
      "value": "V-1002"
    },
    {
      "uuid": "{vendorNameColumnUuid}",
      "value": "Northwind Logistics"
    },
    {
      "uuid": "{countryColumnUuid}",
      "value": "Canada"
    }
  ]
]
```

#### Find a vendor by code

```http
POST /api/v1/dictionary/{dictionaryUuid}/records?offset=0&limit=25
Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {mailboxUuid}

{
  "filters": [
    {
      "uuid": "{vendorCodeColumnUuid}",
      "op": "=",
      "value": "V-1001"
    }
  ]
}
```

The response contains the matching record UUID and all stored values. Save the UUID for later read, update, or delete operations.

### Practical example: Retrieve values for a Dictionary field

A purchase-order template contains a Dictionary field that allows a user to select an approved vendor. The integration retrieves matching values from the Vendor Name column and then reads the selected record to obtain related vendor information.

#### Retrieve matching vendor names

```http
POST /api/v1/dictionary/{dictionaryUuid}/column/{vendorNameColumnUuid}?offset=0&limit=25
Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {mailboxUuid}

{
  "envelopeUuid": "{envelopeUuid}",
  "templateUuid": "{templateUuid}",
  "versionUuid": "{versionUuid}",
  "documentId": "purchase-order",
  "fieldName": "vendor",
  "rowIndex": 0,
  "keyword": "Acme",
  "filter": {}
}
```

The response contains matching display values and their record UUIDs.

```json
{
  "totalElements": 1,
  "sizeRequested": 25,
  "numberOfElements": 1,
  "data": [
    {
      "recordUuid": "{recordUuid}",
      "data": "Acme Corporation"
    }
  ]
}
```

#### Retrieve the selected record

Use the returned `recordUuid` to retrieve the complete vendor record or one related column value.

```http
GET /api/v1/dictionary/{dictionaryUuid}/record/{recordUuid}
Authorization: Bearer {token}
Mailbox: {mailboxUuid}
```

Retrieve one related value directly by its column UUID:

```http
GET /api/v1/dictionary/{dictionaryUuid}/record/{recordUuid}/column/{countryColumnUuid}
Authorization: Bearer {token}
Mailbox: {mailboxUuid}
```

Use the selected vendor record while filling or validating other document fields.

### Related topics

* [Authentication and application tokens](/introduction/authentication-and-application-tokens.md)
* [Envelope fields](/guides/envelope-fields.md)
* [Import Dictionary CSV](/guides/import-dictionary-csv.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)