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.

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

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

Dictionary columns

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

Dictionary records

Method	Endpoint	Purpose
POST	/api/v1/dictionary/{dictionaryUuid}/records	Retrieve records and filter them by column values
POST	/api/v1/dictionary/{dictionaryUuid}/record	Create one or multiple dictionary records
GET	/api/v1/dictionary/{dictionaryUuid}/record/{recordUuid}	Retrieve all values stored in one record
PATCH	/api/v1/dictionary/{dictionaryUuid}/record/{recordUuid}	Update selected column values in an existing record
DELETE	/api/v1/dictionary/{dictionaryUuid}/record	Delete one or multiple records
POST	/api/v1/dictionary/{dictionaryUuid}/record-uuids	Find record UUIDs by values stored in a specific column
GET	/api/v1/dictionary/{dictionaryUuid}/record/{recordUuid}/column/{columnUuid}	Retrieve one column value from a specific record

Dictionary export

Method	Endpoint	Purpose
POST	/api/v1/dictionary/{dictionaryUuid}/download	Start an asynchronous dictionary export in CSV format
GET	/api/v1/dictionary/{dictionaryUuid}/download/status/{taskUuid}	Check the export task and retrieve the generated file URL when it is ready

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.

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.

{
  "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.

[
  [
    {
      "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

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

The response contains the new dictionaryUuid.

{
  "uuid": "{dictionaryUuid}"
}

Configure the dictionary

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.

Column	name	order	width
vendor code	Vendor Code	0	150
vendor name	Vendor Name	1	300
country	Country	2	150

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

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

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

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.

{
  "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.

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

Retrieve one related value directly by its column UUID:

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

• Envelope fields

• Import Dictionary CSV

• Error handling and API error codes