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

# UTM parameters

> Tag destinations so your analytics tool can attribute the traffic.

UTM parameters are appended to the destination URL so Google Analytics, Adobe, or whatever you use can attribute a visit to a campaign. They are read by your analytics tool, not by Dashlink — Dashlink tracks the click regardless.

## Adding them

Set `utm_analytics_enabled=true`, then supply the parameters:

```bash cURL theme={null}
curl -X POST "https://api.dashlink.ai/api/v1/shortlinks/create_shortlink" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -F "destination_url=https://example.com/spring-sale" \
  -F "utm_analytics_enabled=true" \
  -F "utm_source=newsletter" \
  -F "utm_medium=email" \
  -F "utm_campaign=spring-sale-2026"
```

```javascript Node.js theme={null}
const body = new FormData();
body.append("destination_url", "https://example.com/spring-sale");
body.append("utm_analytics_enabled", "true");
body.append("utm_source", "newsletter");
body.append("utm_medium", "email");
body.append("utm_campaign", "spring-sale-2026");

const response = await fetch("https://api.dashlink.ai/api/v1/shortlinks/create_shortlink", {
  method: "POST",
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
  body,
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.dashlink.ai/api/v1/shortlinks/create_shortlink',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
    data={
        'destination_url': 'https://example.com/spring-sale',
        'utm_analytics_enabled': 'true',
        'utm_source': 'newsletter',
        'utm_medium': 'email',
        'utm_campaign': 'spring-sale-2026',
    },
)
payload = response.json()
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"net/url"
	"strings"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/shortlinks/create_shortlink"
	form0 := url.Values{
		"destination_url": {"https://example.com/spring-sale"},
		"utm_analytics_enabled": {"true"},
		"utm_source": {"newsletter"},
		"utm_medium": {"email"},
		"utm_campaign": {"spring-sale-2026"},
	}
	req0, err0 := http.NewRequest("POST", endpoint0, strings.NewReader(form0.Encode()))
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/shortlinks/create_shortlink")
request0 = Net::HTTP::Post.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
request0.set_form_data("destination_url" => "https://example.com/spring-sale", "utm_analytics_enabled" => "true", "utm_source" => "newsletter", "utm_medium" => "email", "utm_campaign" => "spring-sale-2026")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/shortlinks/create_shortlink');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
curl_setopt($ch0, CURLOPT_POSTFIELDS, http_build_query(['destination_url' => 'https://example.com/spring-sale', 'utm_analytics_enabled' => 'true', 'utm_source' => 'newsletter', 'utm_medium' => 'email', 'utm_campaign' => 'spring-sale-2026']));
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

A visitor is sent to:

```
https://example.com/spring-sale?utm_source=newsletter&utm_medium=email&utm_campaign=spring-sale-2026
```

> [!WARNING]
>
> Without `utm_analytics_enabled=true` the UTM fields are stored but not appended. This is the most common reason UTM tagging appears not to work.

## The parameters

| Field | Answers | Example |
| - | - | - |
| `utm_source` | Where did it come from? | `newsletter`, `twitter` |
| `utm_medium` | What kind of channel? | `email`, `cpc`, `social` |
| `utm_campaign` | Which campaign? | `spring-sale-2026` |
| `utm_term` | Which paid keyword? | `running+shoes` |
| `utm_content` | Which variant? | `header-cta`, `variant-b` |
| `utm_id` | Your own campaign id | `CMP-4417` |

`utm_content` is what lets you A/B test: same campaign, different value per variant.

## Consistency is the whole game

UTM values are matched as exact strings. `Email`, `email` and `e-mail` are three different mediums in your reports, and nothing warns you.

Agree a convention and enforce it in code:

* Lowercase everything
* Hyphens, not spaces or underscores
* A fixed vocabulary for `utm_medium`

```python theme={null}
VALID_MEDIUMS = {"email", "social", "cpc", "affiliate", "referral", "print"}

def normalize_utm(value):
    return value.strip().lower().replace(" ", "-").replace("_", "-")

def build_utm(source, medium, campaign, **extra):
    medium = normalize_utm(medium)
    # Catching this here is cheap. Catching it in a report three weeks
    # later means the data is already split and cannot be rejoined.
    if medium not in VALID_MEDIUMS:
        raise ValueError(f"{medium!r} is not one of {sorted(VALID_MEDIUMS)}")

    return {
        "utm_analytics_enabled": "true",
        "utm_source": normalize_utm(source),
        "utm_medium": medium,
        "utm_campaign": normalize_utm(campaign),
        **{k: normalize_utm(v) for k, v in extra.items()},
    }
```

## Templates instead of convention-by-memory

A [UTM template](https://docs.dashlink.ai/api-reference/utm-templates/overview.md) saves a set of values so everyone tags the same way without remembering the rules:

```bash cURL theme={null}
curl -X POST "https://api.dashlink.ai/api/v1/utm_templates/create_utm_template" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -d "template_name=Newsletter" \
  -d "utm_campaign_name=newsletter" \
  -d "utm_source=newsletter" \
  -d "utm_medium=email"
```

```javascript Node.js theme={null}
const body = new URLSearchParams();
body.append("template_name", "Newsletter");
body.append("utm_campaign_name", "newsletter");
body.append("utm_source", "newsletter");
body.append("utm_medium", "email");

const response = await fetch("https://api.dashlink.ai/api/v1/utm_templates/create_utm_template", {
  method: "POST",
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
  body,
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.dashlink.ai/api/v1/utm_templates/create_utm_template',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
    data={
        'template_name': 'Newsletter',
        'utm_campaign_name': 'newsletter',
        'utm_source': 'newsletter',
        'utm_medium': 'email',
    },
)
payload = response.json()
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"net/url"
	"strings"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/utm_templates/create_utm_template"
	form0 := url.Values{
		"template_name": {"Newsletter"},
		"utm_campaign_name": {"newsletter"},
		"utm_source": {"newsletter"},
		"utm_medium": {"email"},
	}
	req0, err0 := http.NewRequest("POST", endpoint0, strings.NewReader(form0.Encode()))
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/utm_templates/create_utm_template")
request0 = Net::HTTP::Post.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
request0.set_form_data("template_name" => "Newsletter", "utm_campaign_name" => "newsletter", "utm_source" => "newsletter", "utm_medium" => "email")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/utm_templates/create_utm_template');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
curl_setopt($ch0, CURLOPT_POSTFIELDS, http_build_query(['template_name' => 'Newsletter', 'utm_campaign_name' => 'newsletter', 'utm_source' => 'newsletter', 'utm_medium' => 'email']));
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

> [!NOTE]
>
> A template is a starting point copied at creation time. Editing it later does not rewrite links already made from it.

## Reading the results back

Dashlink records the UTM values on each click, so you can break analytics down by them without leaving the API:

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=utm_source" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=utm_source", {
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.get(
    'https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=utm_source',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
)
payload = response.json()
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=utm_source"
	req0, err0 := http.NewRequest("GET", endpoint0, nil)
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=utm_source")
request0 = Net::HTTP::Get.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=utm_source');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

`metric` also accepts `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` and `utm_id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.