Lookup Field API

This document contains the Lookup field API format and a list of supported attributes.

Use this page to add a lookup field to template XML. Use lookup fields when one field must show related data from a dictionary field that already exists in the same document.

Lookup field example

<lookup
    name="customer_city"
    placeholder="Select city"
    optional="false"
    allowCustomValue="false"
    search="true"
    documentId="document-id"
    relatedTo="customer"
    columnUuid="22222222-2222-2222-2222-222222222222"
/>

Required attributes

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

• documentId — document ID where the related dictionary field is located.

• relatedTo — name of the dictionary field this lookup depends on.

• 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 lookup list.

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

Rules

• Create the related dictionary field before you use the lookup field.

• Set relatedTo to the exact dictionary field name.

• Use columnUuid to choose which dictionary column the lookup should display.

Related topics

• Template Dynamic Fields API

• Dictionary Field API

• Template Structure API

• Fill Envelope