Docs menu

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

NameInTypeDescription
limitQueryintegerHow many campaigns to return on a page. 1 to 100. Default 15.
pageQueryintegerWhich page to return. At least 1. Default 1.
qQuerystringText to look for in the name.

Example request

Shell
curl "https://siz.la/api/campaigns?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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

  • error is the text "0" on this endpoint and the number 0 on 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

NameInTypeDescription
id (required)PathintegerThe campaign's id. At least 1.
daysQueryintegerHow many days back to report. The plan may keep less history than that. One of 7, 30, 90. Default 30.

Example request

Shell
curl "https://siz.la/api/campaign/12?days=30" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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 data is the number 0 when 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

NameInTypeDescription
name (required)BodystringThe campaign's name. It must be different from your other campaigns. Up to 80 characters.
colorBodystringThe 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_sourceBodystringAdded to the address of every link in the campaign as utm_source. Send an empty string to remove it. Up to 100 characters.
utm_mediumBodystringAdded as utm_medium. Up to 100 characters.
utm_campaignBodystringAdded as utm_campaign. Up to 100 characters.

Example request

Shell
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"}'
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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

NameInTypeDescription
id (required)PathintegerThe campaign's id. At least 1.
nameBodystringThe campaign's name. It must be different from your other campaigns. Up to 80 characters.
colorBodystringThe 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_sourceBodystringAdded to the address of every link in the campaign as utm_source. Send an empty string to remove it. Up to 100 characters.
utm_mediumBodystringAdded as utm_medium. Up to 100 characters.
utm_campaignBodystringAdded as utm_campaign. Up to 100 characters.

Example request

Shell
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"}'
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "error": 0,
    "id": 12,
    "name": "Summer menu"
}

Errors specific to this call

  • 400: A value is not allowed. message says 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

NameInTypeDescription
id (required)PathintegerThe campaign's id. At least 1.

Example request

Shell
curl -X DELETE "https://siz.la/api/campaign/12/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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.

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

NameInTypeDescription
id (required)PathintegerThe campaign's id. At least 1.
link (required)PathintegerThe link's id. At least 1.

Example request

Shell
curl -X POST "https://siz.la/api/campaign/12/assign/1042" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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.