UTM Templates API

Save UTM tag sets once and apply them to any destination URL.

A UTM template is a named set of utm_source, utm_medium and utm_campaign, with optional utm_term and utm_content. The same templates show up in the UTM builder and in the dashboard's create link form.

Template names are unique per workspace, ignoring case. The number of templates depends on the plan: Free 3, Starter 15, Pro and above unlimited.

GET/api/v1/utm-templates

List the workspace's templates, A to Z.

Scope: utm:read

Request

curl https://trimlink.co/api/v1/utm-templates \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

200Response
{
  "success": true,
  "templates": [
  {
    "id": "3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b",
    "name": "Newsletter weekly",
    "source": "newsletter",
    "medium": "email",
    "campaign": "weekly",
    "term": null,
    "content": "header-cta",
    "createdAt": "2026-11-19T10:00:00.000Z",
    "updatedAt": "2026-11-19T10:00:00.000Z"
  }
  ]
}
POST/api/v1/utm-templates

Save a template.

Scope: utm:write

Parameters

NameTypeRequiredDescription
namestringYesTemplate name, 1 to 60 characters.
sourcestringYesUp to 100 characters. Letters, numbers, hyphens, underscores and periods. Saved in lowercase.
mediumstringYesUp to 100 characters. Letters, numbers, hyphens, underscores and periods. Saved in lowercase.
campaignstringYesUp to 100 characters. Letters, numbers, hyphens, underscores and periods. Saved in lowercase.
termstring | nullNoOptional. Same rules.
contentstring | nullNoOptional. Same rules.

Request

curl -X POST https://trimlink.co/api/v1/utm-templates \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter weekly", "source": "newsletter", "medium": "email", "campaign": "weekly", "content": "header-cta"}'

Response

201Response
{
  "success": true,
  "template": {
    "id": "3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b",
    "name": "Newsletter weekly",
    "source": "newsletter",
    "medium": "email",
    "campaign": "weekly",
    "term": null,
    "content": "header-cta",
    "createdAt": "2026-11-19T10:00:00.000Z",
    "updatedAt": "2026-11-19T10:00:00.000Z"
  }
}
PATCH/api/v1/utm-templates/:id

Change any of the fields above. Fields you leave out stay as they are.

Scope: utm:write

Request

curl -X PATCH https://trimlink.co/api/v1/utm-templates/3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"campaign": "monthly"}'

Response

200Response
{
  "success": true,
  "template": {
    "id": "3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b",
    "name": "Newsletter weekly",
    "source": "newsletter",
    "medium": "email",
    "campaign": "monthly",
    "term": null,
    "content": "header-cta",
    "createdAt": "2026-11-19T10:00:00.000Z",
    "updatedAt": "2026-11-19T10:00:00.000Z"
  }
}
DELETE/api/v1/utm-templates/:id

Delete a template. Links already built with it keep their tags.

Scope: utm:write

Request

curl -X DELETE https://trimlink.co/api/v1/utm-templates/3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

204 No Content
POST/api/v1/utm-templates/:id/apply

Return a URL with the template's UTM tags added. Nothing is saved or shortened. Pass the result to POST /api/v1/links to shorten it.

Scope: utm:read

Parameters

NameTypeRequiredDescription
urlstringYesAn http or https URL, up to 2048 characters.

Request

curl -X POST https://trimlink.co/api/v1/utm-templates/3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b/apply \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/pricing"}'

Response

200Response
{
  "success": true,
  "data": {
    "url": "https://example.com/pricing?utm_source=newsletter&utm_medium=email&utm_campaign=weekly&utm_content=header-cta"
  }
}

Errors

These endpoints use the standard error response format.

CodeWhen it happens
400A missing or invalid field, a duplicate template name, or a URL that is not http or https.
403The key is missing the utm:read or utm:write scope, or the plan template limit is reached. Limit errors include tier, limit, current and limitKey ("utmTemplates").
404The template does not exist in this workspace.