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.
/api/v1/utm-templatesList the workspace's templates, A to Z.
utm:readRequest
curl https://trimlink.co/api/v1/utm-templates \
-H "Authorization: Bearer tk_live_your_api_key"Response
{
"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"
}
]
}/api/v1/utm-templatesSave a template.
utm:writeParameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Template name, 1 to 60 characters. |
source | string | Yes | Up to 100 characters. Letters, numbers, hyphens, underscores and periods. Saved in lowercase. |
medium | string | Yes | Up to 100 characters. Letters, numbers, hyphens, underscores and periods. Saved in lowercase. |
campaign | string | Yes | Up to 100 characters. Letters, numbers, hyphens, underscores and periods. Saved in lowercase. |
term | string | null | No | Optional. Same rules. |
content | string | null | No | Optional. 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
{
"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"
}
}/api/v1/utm-templates/:idChange any of the fields above. Fields you leave out stay as they are.
utm:writeRequest
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
{
"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"
}
}/api/v1/utm-templates/:idDelete a template. Links already built with it keep their tags.
utm:writeRequest
curl -X DELETE https://trimlink.co/api/v1/utm-templates/3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b \
-H "Authorization: Bearer tk_live_your_api_key"Response
/api/v1/utm-templates/:id/applyReturn 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.
utm:readParameters
| Name | Type | Required | Description |
|---|---|---|---|
url | string | Yes | An 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
{
"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.
| Code | When it happens |
|---|---|
400 | A missing or invalid field, a duplicate template name, or a URL that is not http or https. |
403 | The 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"). |
404 | The template does not exist in this workspace. |