Create Campaign

POSThttps://viso.li/api/campaign/create

Groups existing short links around a goal so you can track clicks, unique visitors, or compare channels. Campaigns are available on paid plans and always start as ACTIVE.

Send a name, a goal, and at least one link slug you own. Use templateKey to apply a known template. The API stores that key plus a typed goal.config — for example windowDays on a bio campaign.

Send Authorization: Bearer sk_api_your_api_key on every request. See authentication.

Request body

The body must be JSON. Extra keys are rejected. Dates use ISO 8601.

Fields for creating a campaign

Field	Type	Description
`name`	string	Required. Campaign name. 1–100 characters.
`goalType`	string	Required. One of `CLICKS`, `UNIQUE_VISITORS`, or `COMPARE`. Must match the template when that template locks the goal type.
`goalTarget`	number	Target value, at least `1`. Required for `CLICKS` and `UNIQUE_VISITORS` unless `goalConfig.target` is set. Not used for `COMPARE`.
`linkSlugs`	string[]	Required. Slugs of links you own. At least one.
`description`	string	Optional short description. Max 500 characters.
`templateKey`	string	One of `blank`, `general-clicks`, `channel-test`, `content-drop`, `bio-evergreen`, `qr-offline`, or `launch`. Unknown values are rejected. Omit it to skip template defaults.
`goalConfig`	object	Typed goal settings. Shape depends on `goalType`. Extra keys are rejected. See the table below.
`startsAt`	string	ISO 8601 start date. Required for `launch`.
`endsAt`	string	ISO 8601 end date. Required for `launch`. Not allowed for `bio-evergreen`.

Goal config

If you send goalConfig, it must match goalType. If you omit it and send a known template, the API fills in the template default.

Allowed goalConfig fields

Field	Type	Description
`target`	number	Goal value, at least `1`. Used by `CLICKS` and `UNIQUE_VISITORS`.
`windowDays`	number	Rolling click window, `1`–`365`. `CLICKS` only. Bio template default is `30`.
`burstDays`	number	Burst window, `1`–`90`. `UNIQUE_VISITORS` only. Content-drop default is `7`.
`metric`	string	`CLICKS` or `UNIQUE_VISITORS`. `COMPARE` only. Channel-test default is `CLICKS`.

Example request

This creates a bio campaign with a 10,000 click goal. Because templateKey is bio-evergreen and goalConfig is omitted, the stored config includes windowDays: 30.

1curl -X POST https://viso.li/api/campaign/create \

2 -H "Authorization: Bearer sk_api_your_api_key" \

3 -H "Content-Type: application/json" \

4 -d '{

5 "name": "Bio link",

6 "templateKey": "bio-evergreen",

7 "goalType": "CLICKS",

8 "goalTarget": 10000,

9 "linkSlugs": [

10 "abc123"

11 ]

12}'

Success response

Returns 201 Created with the new campaign, including templateKey, typed goal.config, attached links, and current progress.

response.json

2 "id": "3f1c0c2a-7b4e-4d91-9c2a-1b8e6f0d2a11",

3 "name": "Bio link",

4 "description": null,

5 "status": "ACTIVE",

6 "templateKey": "bio-evergreen",

7 "goal": {

8 "type": "CLICKS",

9 "config": {

10 "target": 10000,

11 "windowDays": 30

12 }

13 },

14 "progress": {

15 "type": "CLICKS",

16 "target": 10000,

17 "current": 0,

18 "remaining": 10000,

19 "percent": 0,

20 "reached": false

21 },

22 "linkCount": 1,

23 "links": [

24 {

25 "slug": "abc123",

26 "alias": null,

27 "url": "https://example.com/bio"

28 }

29 ],

30 "startsAt": null,

31 "endsAt": null,

32 "createdAt": "2026-08-22T14:00:00.000Z"

33}

Response fields

Field	Type	Description
`id`	string	Campaign UUID.
`status`	string	Always `ACTIVE` on create.
`goal.config`	object	Typed settings for the stored goal.
`progress`	object	Current vs target. `percent` is 0–100. `reached` is true when the target is met.
`links`	object[]	Attached short links with slug, alias, and destination URL.

Errors

Status	Error	Description
400	Bad Request	Validation failed, a slug is unknown, or a template rule was broken.
401	Unauthorized	Missing, malformed, or invalid Bearer token.
403	Forbidden	Campaigns are not available on the current plan.
429	Too Many Requests	More than 10 requests per minute or 50 requests per day.
500	Internal Server Error	Unexpected server error. Retry the request.