Campaigns API
Make, list, change and delete campaigns, put links in them and read the clicks of a whole campaign with the siz.la REST API.
A campaign groups links so you can read their clicks together and give them the same UTM values. Campaigns are part of the paid plans. Reading needs a key; making, changing, deleting and filling a campaign need a key with write access, like the link calls.
A link joins a campaign in one of three ways: the campaign option when it is made or changed (see (https://siz.la/docs/links)), the assign call below, or a bulk upload in the members area. The campaign's UTM values are added to the link's address, and anything set on the link itself wins.
List campaigns
GET/api/campaigns
Your campaigns by name, with how many links each holds and its clicks over the last 30 days.
Needs: API key. Needs Pro and the plans above it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | Query | integer | How many campaigns to return on a page. 1 to 100. Default 15. |
page | Query | integer | Which page to return. At least 1. Default 1. |
q | Query | string | Text to look for in the name. |
Example request
curl "https://siz.la/api/campaigns?limit=10&page=1" \
-H "Authorization: Bearer $SIZLA_API_KEY"const response = await fetch("https://siz.la/api/campaigns?limit=10&page=1", {
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.get(
"https://siz.la/api/campaigns",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
params={
"limit": 10,
"page": 1,
},
)
print(response.json())$ch = curl_init('https://siz.la/api/campaigns?limit=10&page=1');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": "0",
"data": {
"result": 1,
"perpage": 10,
"currentpage": 1,
"nextpage": null,
"maxpage": 1,
"campaigns": [
{
"id": 12,
"name": "Summer menu",
"color": "ember",
"utm_source": "newsletter",
"utm_medium": "email",
"utm_campaign": "summer-menu",
"links": 8,
"clicks": 412
}
]
}
}Errors specific to this call
403: The plan does not include campaigns.
Notes
erroris the text"0"on this endpoint and the number0on the others.
Get a campaign
GET/api/campaign/{id}
One campaign with its settings, its clicks and where they came from.
Needs: API key. Needs Pro and the plans above it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) | Path | integer | The campaign's id. At least 1. |
days | Query | integer | How many days back to report. The plan may keep less history than that. One of 7, 30, 90. Default 30. |
Example request
curl "https://siz.la/api/campaign/12?days=30" \
-H "Authorization: Bearer $SIZLA_API_KEY"const response = await fetch("https://siz.la/api/campaign/12?days=30", {
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.get(
"https://siz.la/api/campaign/12",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
params={
"days": 30,
},
)
print(response.json())$ch = curl_init('https://siz.la/api/campaign/12?days=30');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"id": 12,
"details": {
"id": 12,
"name": "Summer menu",
"color": "ember",
"utm_source": "newsletter",
"utm_medium": "email",
"utm_campaign": "summer-menu",
"links": 8,
"date": "2026-11-10 08:00:00"
},
"data": {
"days": 30,
"clicks": 412,
"uniqueClicks": 355,
"topCountries": {
"US": 240,
"GB": 61
},
"topReferrers": {
"t.co": 90
},
"topDevices": {
"mobile": 301,
"desktop": 111
},
"topLinks": [
{
"id": 1042,
"shorturl": "https://siz.la/lunch-menu",
"clicks": 37
}
]
}
}Errors specific to this call
403: The plan does not include campaigns.404: The campaign does not exist or belongs to someone else.
Notes
- A list in
datais the number0when there are no clicks to count.
Make a campaign
POST/api/campaign/add
Make a campaign. Put links in it with the campaign option on a link or with the assign call.
Needs: API key with write access. Needs Pro and the plans above it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
name (required) | Body | string | The campaign's name. It must be different from your other campaigns. Up to 80 characters. |
color | Body | string | The color of the campaign's dot in the members area. The default is ink. One of ink, ember, sky, mint, lilac, butter, blush, slate. |
utm_source | Body | string | Added to the address of every link in the campaign as utm_source. Send an empty string to remove it. Up to 100 characters. |
utm_medium | Body | string | Added as utm_medium. Up to 100 characters. |
utm_campaign | Body | string | Added as utm_campaign. Up to 100 characters. |
Example request
curl -X POST "https://siz.la/api/campaign/add" \
-H "Authorization: Bearer $SIZLA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Summer menu","utm_source":"newsletter","utm_medium":"email"}'const response = await fetch("https://siz.la/api/campaign/add", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "Summer menu",
"utm_source": "newsletter",
"utm_medium": "email"
}),
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.post(
"https://siz.la/api/campaign/add",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
json={
"name": "Summer menu",
"utm_source": "newsletter",
"utm_medium": "email",
},
)
print(response.json())$ch = curl_init('https://siz.la/api/campaign/add');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Summer menu',
'utm_source' => 'newsletter',
'utm_medium' => 'email',
]),
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"id": 12,
"name": "Summer menu"
}Errors specific to this call
400: The name is missing or already used, a value is not allowed, or the account has the most campaigns it can keep.403: The plan does not include campaigns.
Update a campaign
PUT/api/campaign/{id}/update
Change a campaign. Only the fields you send change. New UTM values reach a link the next time it is saved or added to the campaign.
Needs: API key with write access. Needs Pro and the plans above it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) | Path | integer | The campaign's id. At least 1. |
name | Body | string | The campaign's name. It must be different from your other campaigns. Up to 80 characters. |
color | Body | string | The color of the campaign's dot in the members area. The default is ink. One of ink, ember, sky, mint, lilac, butter, blush, slate. |
utm_source | Body | string | Added to the address of every link in the campaign as utm_source. Send an empty string to remove it. Up to 100 characters. |
utm_medium | Body | string | Added as utm_medium. Up to 100 characters. |
utm_campaign | Body | string | Added as utm_campaign. Up to 100 characters. |
Example request
curl -X PUT "https://siz.la/api/campaign/12/update" \
-H "Authorization: Bearer $SIZLA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"utm_campaign":"summer-menu-2026"}'const response = await fetch("https://siz.la/api/campaign/12/update", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"utm_campaign": "summer-menu-2026"
}),
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.put(
"https://siz.la/api/campaign/12/update",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
json={
"utm_campaign": "summer-menu-2026",
},
)
print(response.json())$ch = curl_init('https://siz.la/api/campaign/12/update');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'utm_campaign' => 'summer-menu-2026',
]),
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"id": 12,
"name": "Summer menu"
}Errors specific to this call
400: A value is not allowed.messagesays which.403: The plan does not include campaigns.404: The campaign does not exist or belongs to someone else.
Delete a campaign
DELETE/api/campaign/{id}/delete
Delete a campaign. Its links keep working and leave the campaign.
Needs: API key with write access. Needs Pro and the plans above it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) | Path | integer | The campaign's id. At least 1. |
Example request
curl -X DELETE "https://siz.la/api/campaign/12/delete" \
-H "Authorization: Bearer $SIZLA_API_KEY"const response = await fetch("https://siz.la/api/campaign/12/delete", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.delete(
"https://siz.la/api/campaign/12/delete",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())$ch = curl_init('https://siz.la/api/campaign/12/delete');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"message": "Campaign has been deleted successfully"
}Errors specific to this call
403: The plan does not include campaigns.404: The campaign does not exist or belongs to someone else.
Put a link in a campaign
POST/api/campaign/{id}/assign/{link}
Move one of your links into a campaign. The campaign's UTM values are added to the link's address.
Needs: API key with write access. Needs Pro and the plans above it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) | Path | integer | The campaign's id. At least 1. |
link (required) | Path | integer | The link's id. At least 1. |
Example request
curl -X POST "https://siz.la/api/campaign/12/assign/1042" \
-H "Authorization: Bearer $SIZLA_API_KEY"const response = await fetch("https://siz.la/api/campaign/12/assign/1042", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.post(
"https://siz.la/api/campaign/12/assign/1042",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())$ch = curl_init('https://siz.la/api/campaign/12/assign/1042');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"message": "Link has been assigned to the campaign."
}Errors specific to this call
403: The plan does not include campaigns.404: The campaign or the link does not exist or belongs to someone else.
Notes
- To take a link out of a campaign, update the link with an empty
campaign.