Adding them
Setutm_analytics_enabled=true, then supply the parameters:
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"
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();
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()
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))
}
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
$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);
https://example.com/spring-sale?utm_source=newsletter&utm_medium=email&utm_campaign=spring-sale-2026
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
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 saves a set of values so everyone tags the same way without remembering the rules: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"
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();
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()
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))
}
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
$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);
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: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"
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();
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()
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))
}
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
$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.