UTM Templates
utm-templates:read to list templates, and utm-templates:write to create,
change and delete them.A UTM template is a saved set of UTM parameters that links in a
workspace can use. Identify a template by its public_id. To use a template on a link, send
its public ID as utm_template_id when you create or update the link.
Endpoints
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/workspaces/{workspace_public_id}/utm-templates | utm-templates:read |
POST | /api/v1/workspaces/{workspace_public_id}/utm-templates | utm-templates:write |
PUT | /api/v1/utm-templates/{template_public_id} | utm-templates:write |
DELETE | /api/v1/utm-templates/{template_public_id} | utm-templates:write |
Owners, administrators and collaborators can create, change and delete templates. Read-only members can only list them.
The template object
{
"public_id": "c41d8e7a-2b9f-4c36-8a15-7e0f3d6b9a42",
"workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
"team_public_id": "",
"team_name": "",
"team_public_ids": [],
"team_names": [],
"workspace_wide": true,
"name": "Newsletter",
"utm_source": "newsletter",
"utm_medium": "email",
"utm_campaign": "november",
"utm_term": "",
"utm_content": "",
"utm_id": "",
"created_at": "2026-11-02T09:00:00Z",
"updated_at": "2026-11-02T09:00:00Z"
}| Field | Notes |
|---|---|
team_public_ids, team_names | The teams the template is limited to. Empty when the template is workspace-wide. |
team_public_id, team_name | The first of those teams, kept for older integrations. |
utm_* | The six UTM values. An empty string means the parameter isn’t set. |
List templates
By default the list returns only workspace-wide templates, sorted by name. To include team templates:
| Query parameter | Notes |
|---|---|
include_team_scoped | 1 or true adds the team templates you can see. |
team_public_ids | Team public IDs, comma-separated or as a JSON array. Returns workspace-wide templates and the templates assigned to every listed team. |
Workspace owners and administrators can see every template; other members see the templates of teams they belong to.
curl "https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/utm-templates?include_team_scoped=1" \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"data": [
{
"public_id": "c41d8e7a-2b9f-4c36-8a15-7e0f3d6b9a42",
"workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
"team_public_id": "",
"team_name": "",
"team_public_ids": [],
"team_names": [],
"workspace_wide": true,
"name": "Newsletter",
"utm_source": "newsletter",
"utm_medium": "email",
"utm_campaign": "november",
"utm_term": "",
"utm_content": "",
"utm_id": "",
"created_at": "2026-11-02T09:00:00Z",
"updated_at": "2026-11-02T09:00:00Z"
}
]
}Create a template
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | No | Up to 120 characters. Defaults to Untitled Template. |
utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id | string | No | Up to 100 characters each. No line breaks or other control characters. |
team_public_ids | array of strings | No | Teams to limit the template to. Leave it out for a workspace-wide template. |
curl -X POST https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/utm-templates \
-H "Authorization: Bearer $SHORTN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Newsletter", "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "november"}'The response is 201, with the template object in data.
The limit counts every template in all the workspaces of the workspace’s owner. When it’s
reached, you get 403:
{
"code": "plan_limit_exceeded",
"error": "UTM template limit reached for this workspace owner's current plan",
"hint": "Upgrade to a plan that includes this feature or raises this limit.",
"feature": "utm_templates",
"limit": 3,
"current": 3,
"required_plan": null,
"upgrade_url": "/profile/billing"
}Update a template
PUT replaces the template: send every value you want to keep. An empty or missing UTM
value is cleared, and a missing name becomes Untitled Template. The new values are
applied to every link that uses the template.
| Field | Type | Required | Notes |
|---|---|---|---|
name, utm_* | string | No | As when creating. |
team_public_ids | array of strings | No | The template’s complete list of teams. Send [] to make it workspace-wide. Leave it out to keep the current teams. |
workspace_public_id | string | No | Moves the template to another workspace you can edit. A key restricted to one workspace can’t move templates. |
lost_access_action | string | When needed | remove or copy. See below. |
curl -X PUT https://app.shortn.link/api/v1/utm-templates/c41d8e7a-2b9f-4c36-8a15-7e0f3d6b9a42 \
-H "Authorization: Bearer $SHORTN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Newsletter", "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "december"}'The response is the template object in data, plus move_impact
(see below).
Links that would lose the template
Moving a template, or limiting it to teams, can leave links using it that the template no
longer reaches. In that case the update stops with 409 and lists up to 10 of those links:
{
"error": "lost_access_action_required",
"impact": {
"count": 2,
"links": [
{
"public_id": "0d3b5f7a-8c1e-4a92-b6d4-2e9f7a1c3b58",
"title": "Black Friday",
"short_code": "bf26",
"workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
"workspace_name": "Acme Marketing",
"team_public_id": "",
"team_name": ""
}
]
}
}Send the request again with lost_access_action to say what happens to those links:
remove: the template and its UTM values are removed from those links.copy: those links keep the UTM values as their own, without the template.
Moving a template to a workspace owned by someone else counts against that owner’s template limit.
Delete a template
| Query parameter | Notes |
|---|---|
links | keep (the default) leaves the template’s values on its links as their own. clear removes them from the links too. |
curl -X DELETE "https://app.shortn.link/api/v1/utm-templates/c41d8e7a-2b9f-4c36-8a15-7e0f3d6b9a42?links=keep" \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"data": {
"public_id": "c41d8e7a-2b9f-4c36-8a15-7e0f3d6b9a42",
"deleted": true,
"links": "keep",
"links_updated": 12
}
}Errors
| Status | code | When |
|---|---|---|
400 | invalid_request_format | The body isn’t valid JSON. |
400 | invalid_template_id | The ID isn’t a template public_id. |
400 | template_name_too_long | name is over 120 characters. |
400 | utm_value_too_long, utm_value_invalid | A UTM value is over 100 characters or has control characters. details.field names it. |
400 | invalid_links_mode | links isn’t keep or clear. |
400 | invalid_utm_template | A team in team_public_ids is unknown or in another workspace. |
403 | workspace_permission_denied | You’re a read-only member creating a template. Updating one as a read-only member returns 403 with only error: no permission to manage template. |
403 | plan_limit_exceeded | The owner’s template limit is reached. |
403 | api_key_workspace_mismatch | The template is in another workspace than the key’s, or the update would move it out. |
404 | utm_template_not_found | The template doesn’t exist, or you can’t see it. |
409 | workspace_archived | The template’s workspace is archived. |
409 | lost_access_action_required | See links that would lose the template. This response has error but no code. |
The workspace in the path is checked first:
400invalid_workspace_id;404workspace_not_found, which an archived workspace also returns.
Errors every endpoint can return (a missing key, a missing scope, rate limits) are listed on authentication.