> 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-documentation/template-api/template-dynamic-fields-api/lookup-field-api.md).

# Lookup Field API

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

```xml
<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](/api-documentation/template-api/template-dynamic-fields-api.md)
* [Dictionary Field API](/api-documentation/template-api/template-dynamic-fields-api/dictionary-field-api.md)
* [Template Structure API](/api-documentation/template-api/template-structure-api.md)
* [Fill Envelope](/api-documentation/envelope/fill-envelope.md)