Dictionary Field API

This document contains the Dictionary field API format, attributes, and filterQuery examples.

Use this page to add a dictionary field to template XML. Assign the field to a role with roleId, then let the recipient select a value from a predefined dataset.

Dictionary field example

<field
    type="select-dictionary"
    name="customer"
    placeholder="Select customer"
    roleId="fd8cb669-db1d-41e1-8f6c-2ad3f8fa981a"
    optional="false"
    allowCustomValue="false"
    search="true"
    dictionaryUuid="11111111-1111-1111-1111-111111111111"
    columnUuid="22222222-2222-2222-2222-222222222222"
/>

Required attributes

• type — field type. Use select-dictionary.

• name — field name. Use 1 to 128 characters. Do not use &, ", <, or >. Keep the value unique within one document.

• roleId — role identifier for the recipient who fills the field.

• dictionaryUuid — source dictionary UUID.

• columnUuid — dictionary column UUID whose value the field should display as text.

Optional attributes

• placeholder — placeholder text shown in the template and envelope. Use 0 to 1024 characters. If you omit it, the envelope shows the field name.

• optional — set to true if the recipient can leave the field empty. If you omit it, the default value is false.

• allowCustomValue — set to true if the recipient can enter a value outside the dictionary list.

• search — set to true if the field value should be available in envelope search. If you omit it, the default value is false.

• filterQuery — serialized JSON string that limits the available dictionary values. Use this attribute when the dictionary uses filtering.

Filter query examples

Filter by a field value from the same envelope:

{"dictionaryColumnUUID":{"documentId":"document-id","fieldName":"field-name"}}

• dictionaryColumnUUID — dictionary column UUID used for filtering.

• documentId — document ID that contains the source field.

• fieldName — source field name from the envelope.

Filter by the active role:

{"dictionaryColumnUUID":{"roleId":"role-id"}}

• dictionaryColumnUUID — dictionary column UUID used for filtering.

• roleId — role ID used for filtering.

Related topics

• Template Dynamic Fields API

• Template Structure API

• Send Envelope

• Fill Envelope