Skip to content
UTM Templates

UTM Templates

Availability: UTM templates are available on every plan, including Free. The number of templates depends on the workspace owner’s plan (see plans). API keys need 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

MethodPathScope
GET/api/v1/workspaces/{workspace_public_id}/utm-templatesutm-templates:read
POST/api/v1/workspaces/{workspace_public_id}/utm-templatesutm-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"
}
FieldNotes
team_public_ids, team_namesThe teams the template is limited to. Empty when the template is workspace-wide.
team_public_id, team_nameThe 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 parameterNotes
include_team_scoped1 or true adds the team templates you can see.
team_public_idsTeam 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

FieldTypeRequiredNotes
namestringNoUp to 120 characters. Defaults to Untitled Template.
utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_idstringNoUp to 100 characters each. No line breaks or other control characters.
team_public_idsarray of stringsNoTeams 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.

FieldTypeRequiredNotes
name, utm_*stringNoAs when creating.
team_public_idsarray of stringsNoThe template’s complete list of teams. Send [] to make it workspace-wide. Leave it out to keep the current teams.
workspace_public_idstringNoMoves the template to another workspace you can edit. A key restricted to one workspace can’t move templates.
lost_access_actionstringWhen neededremove 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 parameterNotes
linkskeep (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

StatuscodeWhen
400invalid_request_formatThe body isn’t valid JSON.
400invalid_template_idThe ID isn’t a template public_id.
400template_name_too_longname is over 120 characters.
400utm_value_too_long, utm_value_invalidA UTM value is over 100 characters or has control characters. details.field names it.
400invalid_links_modelinks isn’t keep or clear.
400invalid_utm_templateA team in team_public_ids is unknown or in another workspace.
403workspace_permission_deniedYou’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.
403plan_limit_exceededThe owner’s template limit is reached.
403api_key_workspace_mismatchThe template is in another workspace than the key’s, or the update would move it out.
404utm_template_not_foundThe template doesn’t exist, or you can’t see it.
409workspace_archivedThe template’s workspace is archived.
409lost_access_action_requiredSee links that would lose the template. This response has error but no code.

The workspace in the path is checked first:

  • 400 invalid_workspace_id;
  • 404 workspace_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.

Last updated on