> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terminus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Tagged URL field

> A computed field that builds a destination URL with UTM query parameters drawn from other fields on the same record.

<Info>
  A **Tagged URL** field is computed. It takes a base URL from another field, then appends query parameters whose values come from other fields on the same record. This is how you turn a plain destination into a fully UTM-tagged link like `…/deals?utm_source=newsletter&utm_medium=email&utm_campaign=awareness-us`.
</Info>

## When to use it

* Attaching UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, and so on) to a campaign's destination URL.
* Assembling any URL from a base plus one or more field-derived query parameters.
* Producing a tagged destination for a [Short URL](/reference/fields/short-url) field to wrap, so the short link redirects to an already-tagged URL.

<Warning>
  Don't use a Tagged URL field to compose a plain string. If you only need to join values (for example, to build the `utm_campaign` value itself), use a [Concatenation](/reference/fields/concatenation) field.
</Warning>

## How it is configured

A Tagged URL field is computed, so it is always required and submitters never type into it. In the field editor you set:

| Setting                       | Required | Default | What it does                                                                                                                                                                            |
| ----------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url_field_id`                | Yes      | None    | The base URL. You select another field on the taxonomy whose type is [URL](/reference/fields), [Tagged URL](/reference/fields/tagged-url), or [Short URL](/reference/fields/short-url). |
| `parameters`                  | Yes      | None    | The ordered list of query parameters to append. Each entry has a `key` and a field to read the value from. The list can be empty if you only want to pass the base URL through.         |
| `parameters[].key`            | Yes      | None    | The query parameter name, for example `utm_source`. Keys must be unique within the field.                                                                                               |
| `parameters[].value_field_id` | Yes      | None    | The field whose value becomes this parameter's value. Any field type is allowed; the value is read as a string.                                                                         |
| `unique`                      | No       | `false` | When on, the computed URL must be unique across the account's records.                                                                                                                  |

When the submission is saved, Terminus reads the base URL, then walks the parameter list in order. For each parameter, it reads the value field. If that value is blank, the parameter is skipped and its key does not appear in the output. Otherwise the `key=value` pair is appended to the URL's query string. Values are URL-encoded automatically.

## A worked example

In the Campaign URL Builder, a `tagged_url` field combines the campaign's `destination_url` with three UTM parameters.

```yaml theme={null}
type: tagged_url
settings:
  url_field_id: destination_url
  parameters:
    - { key: utm_source,   value_field_id: utm_source }
    - { key: utm_medium,   value_field_id: utm_medium }
    - { key: utm_campaign, value_field_id: utm_campaign }
```

For a submission where `destination_url` is `https://shop.acme.example/deals`, `utm_source` is `newsletter`, `utm_medium` is `email`, and `utm_campaign` is `awareness-us-black_friday`, the field computes:

```text theme={null}
https://shop.acme.example/deals?utm_source=newsletter&utm_medium=email&utm_campaign=awareness-us-black_friday
```

The `utm_campaign` value here is itself produced by a [Concatenation](/reference/fields/concatenation) field, and a [Short URL](/reference/fields/short-url) field then wraps this Tagged URL so the campaign gets a branded short link.

## Gotchas

* **The base URL field can itself be computed.** `url_field_id` accepts URL, Tagged URL, and Short URL fields, which lets you chain them (raw URL, then tagged URL, then short URL). The trade-off is that if the upstream field produces a blank value, the Tagged URL output is empty too.
* **Blank parameter values are dropped, not rendered empty.** If `utm_source` is blank on a submission, the output has no `utm_source=` at all rather than an empty `utm_source=`. To guarantee a key is always present, make its value field required.
* **Values are always URL-encoded.** Each parameter value is encoded when the URL is built, so a value with spaces or reserved characters is made URL-safe automatically. You don't (and can't) turn this off per parameter, so don't pre-encode values yourself or they will be double-encoded.
* **Query parameters already on the base URL are kept.** If the base URL is `…/deals?ref=partner`, the output keeps `ref=partner` and appends your declared parameters after it. Duplicate keys are not removed; the declared parameters are appended last.
* **Renaming a parameter `key` only affects new submissions.** Existing approved records keep their stored URL. There is no automatic backfill.

## Related

* [Field types overview](/reference/fields)
* [Concatenation field](/reference/fields/concatenation): for building the `utm_campaign` value that feeds a parameter.
* [Short URL field](/reference/fields/short-url): the usual downstream wrapper for a Tagged URL.
* [UTM tagging recipe](/recipes/tagged-url-utm)