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

# Dictionaries

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

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="100">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="102.4444580078125">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="100.22222900390625">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="102.44439697265625">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

{% tabs %}
{% tab title="Node.js" %}

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

const response = await fetch(
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  }
);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$body = [
    "name" => "Vendor Directory",
    "description" => "Approved vendors synchronized from the ERP system",
    "access" => "mailbox",
    "filteredAccessOnly" => false
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}"
);
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json"
    ]
]);
$response = curl_exec($curl);
curl_close($curl);
```

{% endtab %}

{% tab title="Python" %}

```python
body = {
    "name": "Vendor Directory",
    "description": "Approved vendors synchronized from the ERP system",
    "access": "mailbox",
    "filteredAccessOnly": False
}
response = requests.patch(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}",
    headers={"Authorization": "Bearer {token}", "Mailbox": "{mailboxUuid}"},
    json=body
)
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "net/http"
require "json"

uri = URI("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}")
request = Net::HTTP::Patch.new(
  uri,
  {
    "Authorization" => "Bearer {token}",
    "Mailbox" => "{mailboxUuid}",
    "Content-Type" => "application/json"
  }
)
request.body = {
  name: "Vendor Directory",
  description: "Approved vendors synchronized from the ERP system",
  access: "mailbox",
  filteredAccessOnly: false
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true
) { |http| http.request(request) }
```

{% endtab %}

{% tab title="Go" %}

```go
body := strings.NewReader(`{
  "name": "Vendor Directory",
  "description": "Approved vendors synchronized from the ERP system",
  "access": "mailbox",
  "filteredAccessOnly": false
}`)

request, err := http.NewRequest(
  http.MethodPatch,
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}",
  body,
)
if err != nil {
  panic(err)
}

request.Header.Set("Authorization", "Bearer {token}")
request.Header.Set("Mailbox", "{mailboxUuid}")
request.Header.Set("Content-Type", "application/json")

response, err := http.DefaultClient.Do(request)
if err != nil {
  panic(err)
}
defer response.Body.Close()
```

{% endtab %}

{% tab title="Java" %}

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

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}"))
    .header("Authorization", "Bearer {token}")
    .header("Mailbox", "{mailboxUuid}")
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(
    request,
    HttpResponse.BodyHandlers.ofString()
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Json;

using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Patch,
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}"
);

request.Headers.Add("Authorization", "Bearer {token}");
request.Headers.Add("Mailbox", "{mailboxUuid}");
request.Content = JsonContent.Create(new
{
    name = "Vendor Directory",
    description = "Approved vendors synchronized from the ERP system",
    access = "mailbox",
    filteredAccessOnly = false
});

using var response = await client.SendAsync(request);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request PATCH \
  --url "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}" \
  --header "Authorization: Bearer {token}" \
  --header "Mailbox: {mailboxUuid}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Vendor Directory",
    "description": "Approved vendors synchronized from the ERP system",
    "access": "mailbox",
    "filteredAccessOnly": false
  }'
```

{% endtab %}
{% endtabs %}

#### 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>

{% tabs %}
{% tab title="Node.js" %}

```javascript
const body = {
  name: "Vendor Code",
  order: 0,
  width: 150,
  longText: false
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  }
);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$body = [
    "name" => "Vendor Code",
    "order" => 0,
    "width" => 150,
    "longText" => false
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column"
);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json"
    ]
]);
$response = curl_exec($curl);
curl_close($curl);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

body = {
    "name": "Vendor Code",
    "order": 0,
    "width": 150,
    "longText": False
}

response = requests.post(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}"
    },
    json=body
)
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "net/http"
require "json"

uri = URI("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column")
request = Net::HTTP::Post.new(
  uri,
  {
    "Authorization" => "Bearer {token}",
    "Mailbox" => "{mailboxUuid}",
    "Content-Type" => "application/json"
  }
)
request.body = {
  name: "Vendor Code",
  order: 0,
  width: 150,
  longText: false
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true
) { |http| http.request(request) }
```

{% endtab %}

{% tab title="Go" %}

```go
body := strings.NewReader(`{
  "name": "Vendor Code",
  "order": 0,
  "width": 150,
  "longText": false
}`)

request, err := http.NewRequest(
  http.MethodPost,
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column",
  body,
)
if err != nil {
  panic(err)
}

request.Header.Set("Authorization", "Bearer {token}")
request.Header.Set("Mailbox", "{mailboxUuid}")
request.Header.Set("Content-Type", "application/json")

response, err := http.DefaultClient.Do(request)
if err != nil {
  panic(err)
}
defer response.Body.Close()
```

{% endtab %}

{% tab title="Java" %}

```java
String body = """
{
  "name": "Vendor Code",
  "order": 0,
  "width": 150,
  "longText": false
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column"))
    .header("Authorization", "Bearer {token}")
    .header("Mailbox", "{mailboxUuid}")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(
    request,
    HttpResponse.BodyHandlers.ofString()
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer {token}");
client.DefaultRequestHeaders.Add("Mailbox", "{mailboxUuid}");

var body = new
{
    name = "Vendor Code",
    order = 0,
    width = 150,
    longText = false
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column",
    body
);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column" \
  --header "Authorization: Bearer {token}" \
  --header "Mailbox: {mailboxUuid}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Vendor Code",
    "order": 0,
    "width": 150,
    "longText": false
  }'
```

{% endtab %}
{% endtabs %}

#### Create vendor records

{% tabs %}
{% tab title="Node.js" %}

```javascript
const records = [
  [
    { 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" }
  ]
];

const response = await fetch(
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/record",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(records)
  }
);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$records = [
    [
        ["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"]
    ]
];

$curl = curl_init("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/record");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($records),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json"
    ]
]);
$response = curl_exec($curl);
curl_close($curl);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

records = [
    [
        {"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"}
    ]
]

response = requests.post(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/record",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}"
    },
    json=records
)
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "net/http"
require "json"

records = [
  [
    { 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" }
  ]
]

uri = URI("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/record")
request = Net::HTTP::Post.new(uri, {
  "Authorization" => "Bearer {token}",
  "Mailbox" => "{mailboxUuid}",
  "Content-Type" => "application/json"
})
request.body = records.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
```

{% endtab %}

{% tab title="Go" %}

```go
body := strings.NewReader(`[
  [
    {"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"}
  ]
]`)

request, err := http.NewRequest(
  http.MethodPost,
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/record",
  body,
)
if err != nil {
  panic(err)
}
request.Header.Set("Authorization", "Bearer {token}")
request.Header.Set("Mailbox", "{mailboxUuid}")
request.Header.Set("Content-Type", "application/json")

response, err := http.DefaultClient.Do(request)
if err != nil {
  panic(err)
}
defer response.Body.Close()
```

{% endtab %}

{% tab title="Java" %}

```java
String body = """
[
  [
    {"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"}
  ]
]
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/record"))
    .header("Authorization", "Bearer {token}")
    .header("Mailbox", "{mailboxUuid}")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(
    request,
    HttpResponse.BodyHandlers.ofString()
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer {token}");
client.DefaultRequestHeaders.Add("Mailbox", "{mailboxUuid}");

var records = new[]
{
    new[]
    {
        new { uuid = "{vendorCodeColumnUuid}", value = "V-1001" },
        new { uuid = "{vendorNameColumnUuid}", value = "Acme Corporation" },
        new { uuid = "{countryColumnUuid}", value = "United States" }
    },
    new[]
    {
        new { uuid = "{vendorCodeColumnUuid}", value = "V-1002" },
        new { uuid = "{vendorNameColumnUuid}", value = "Northwind Logistics" },
        new { uuid = "{countryColumnUuid}", value = "Canada" }
    }
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/record",
    records
);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/record" \
  --header "Authorization: Bearer {token}" \
  --header "Mailbox: {mailboxUuid}" \
  --header "Content-Type: application/json" \
  --data '[
    [
      {"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"}
    ]
  ]'
```

{% endtab %}
{% endtabs %}

#### Find a vendor by code

{% tabs %}
{% tab title="Node.js" %}

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

const response = await fetch(
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/records?offset=0&limit=25",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  }
);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$body = [
    "filters" => [
        [
            "uuid" => "{vendorCodeColumnUuid}",
            "op" => "=",
            "value" => "V-1001"
        ]
    ]
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/records?offset=0&limit=25"
);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json"
    ]
]);
$response = curl_exec($curl);
curl_close($curl);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

response = requests.post(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/records?offset=0&limit=25",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}"
    },
    json=body
)
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "net/http"
require "json"

uri = URI("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/records?offset=0&limit=25")
request = Net::HTTP::Post.new(uri, {
  "Authorization" => "Bearer {token}",
  "Mailbox" => "{mailboxUuid}",
  "Content-Type" => "application/json"
})
request.body = {
  filters: [
    {
      uuid: "{vendorCodeColumnUuid}",
      op: "=",
      value: "V-1001"
    }
  ]
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
```

{% endtab %}

{% tab title="Go" %}

```go
body := strings.NewReader(`{
  "filters": [
    {
      "uuid": "{vendorCodeColumnUuid}",
      "op": "=",
      "value": "V-1001"
    }
  ]
}`)

request, err := http.NewRequest(
  http.MethodPost,
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/records?offset=0&limit=25",
  body,
)
if err != nil {
  panic(err)
}
request.Header.Set("Authorization", "Bearer {token}")
request.Header.Set("Mailbox", "{mailboxUuid}")
request.Header.Set("Content-Type", "application/json")

response, err := http.DefaultClient.Do(request)
if err != nil {
  panic(err)
}
defer response.Body.Close()
```

{% endtab %}

{% tab title="Java" %}

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

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/records?offset=0&limit=25"))
    .header("Authorization", "Bearer {token}")
    .header("Mailbox", "{mailboxUuid}")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(
    request,
    HttpResponse.BodyHandlers.ofString()
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer {token}");
client.DefaultRequestHeaders.Add("Mailbox", "{mailboxUuid}");

var body = new
{
    filters = new[]
    {
        new
        {
            uuid = "{vendorCodeColumnUuid}",
            op = "=",
            value = "V-1001"
        }
    }
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/records?offset=0&limit=25",
    body
);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/records?offset=0&limit=25" \
  --header "Authorization: Bearer {token}" \
  --header "Mailbox: {mailboxUuid}" \
  --header "Content-Type: application/json" \
  --data '{
    "filters": [
      {
        "uuid": "{vendorCodeColumnUuid}",
        "op": "=",
        "value": "V-1001"
      }
    ]
  }'
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Node.js" %}

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

const response = await fetch(
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column/{vendorNameColumnUuid}?offset=0&limit=25",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  }
);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$body = [
    "envelopeUuid" => "{envelopeUuid}",
    "templateUuid" => "{templateUuid}",
    "versionUuid" => "{versionUuid}",
    "documentId" => "purchase-order",
    "fieldName" => "vendor",
    "rowIndex" => 0,
    "keyword" => "Acme",
    "filter" => new stdClass()
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column/{vendorNameColumnUuid}?offset=0&limit=25"
);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json"
    ]
]);
$response = curl_exec($curl);
curl_close($curl);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

response = requests.post(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column/{vendorNameColumnUuid}?offset=0&limit=25",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}"
    },
    json=body
)
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "net/http"
require "json"

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

uri = URI("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column/{vendorNameColumnUuid}?offset=0&limit=25")
request = Net::HTTP::Post.new(uri, {
  "Authorization" => "Bearer {token}",
  "Mailbox" => "{mailboxUuid}",
  "Content-Type" => "application/json"
})
request.body = body.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
```

{% endtab %}

{% tab title="Go" %}

```go
body := strings.NewReader(`{
  "envelopeUuid": "{envelopeUuid}",
  "templateUuid": "{templateUuid}",
  "versionUuid": "{versionUuid}",
  "documentId": "purchase-order",
  "fieldName": "vendor",
  "rowIndex": 0,
  "keyword": "Acme",
  "filter": {}
}`)

request, err := http.NewRequest(
  http.MethodPost,
  "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column/{vendorNameColumnUuid}?offset=0&limit=25",
  body,
)
if err != nil {
  panic(err)
}
request.Header.Set("Authorization", "Bearer {token}")
request.Header.Set("Mailbox", "{mailboxUuid}")
request.Header.Set("Content-Type", "application/json")

response, err := http.DefaultClient.Do(request)
if err != nil {
  panic(err)
}
defer response.Body.Close()
```

{% endtab %}

{% tab title="Java" %}

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

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column/{vendorNameColumnUuid}?offset=0&limit=25"))
    .header("Authorization", "Bearer {token}")
    .header("Mailbox", "{mailboxUuid}")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(
    request,
    HttpResponse.BodyHandlers.ofString()
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer {token}");
client.DefaultRequestHeaders.Add("Mailbox", "{mailboxUuid}");

var body = new
{
    envelopeUuid = "{envelopeUuid}",
    templateUuid = "{templateUuid}",
    versionUuid = "{versionUuid}",
    documentId = "purchase-order",
    fieldName = "vendor",
    rowIndex = 0,
    keyword = "Acme",
    filter = new { }
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column/{vendorNameColumnUuid}?offset=0&limit=25",
    body
);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.docstudio.com/api/v1/dictionary/{dictionaryUuid}/column/{vendorNameColumnUuid}?offset=0&limit=25" \
  --header "Authorization: Bearer {token}" \
  --header "Mailbox: {mailboxUuid}" \
  --header "Content-Type: application/json" \
  --data '{
    "envelopeUuid": "{envelopeUuid}",
    "templateUuid": "{templateUuid}",
    "versionUuid": "{versionUuid}",
    "documentId": "purchase-order",
    "fieldName": "vendor",
    "rowIndex": 0,
    "keyword": "Acme",
    "filter": {}
  }'
```

{% endtab %}
{% endtabs %}

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)