Viso.li

Create Campaign

POSThttps://www.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. Unknown top-level keys are ignored. Dates use ISO 8601.

Fields

FieldTypeDescription
namestringRequired. Campaign name. 1–100 characters.
descriptionobjectRequired. Optional short description. Max 500 characters.
templateKeyobjectOne of blank, general-clicks, channel-test, content-drop, bio-evergreen, qr-offline, or launch. Omit it to skip template defaults.
startsAtstringISO 8601 start date. Required for launch.
endsAtstringISO 8601 end date. Required for launch. Not allowed for bio-evergreen.
goalTypestringRequired. One of CLICKS, UNIQUE_VISITORS, or COMPARE. Must match the template when that template locks the goal type.
goalTargetnumberTarget value, at least 1. Required for CLICKS and UNIQUE_VISITORS unless goalConfig.target is set. Not used for COMPARE.
goalConfigobjectTyped goal settings. Shape depends on goalType. Unknown keys inside goalConfig are rejected.
linkSlugsstring[]Required. Slugs of links you own. At least one.

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.

FieldTypeDescription
targetnumberRequired. Goal value, at least 1. Used by CLICKS and UNIQUE_VISITORS.
windowDaysnumberRolling click window, 1–365. CLICKS only. Bio template default is 30.
burstDaysnumberBurst window, 1–90. UNIQUE_VISITORS only. Content-drop default is 7.
metricstringRequired. 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://www.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
1{
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

FieldTypeDescription
idstringRequired. Campaign UUID.
namestringRequired. Campaign name.
descriptionstring | nullRequired. Short description, or null.
statusstringRequired. ACTIVE, DRAFT, or ENDED.
templateKeystring | nullRequired. Stored template key, or null.
goalobject | nullRequired. Typed goal settings stored for this campaign.
progressobject | nullRequired. Current vs target, when the goal is numeric.
linkCountnumberRequired. Number of attached links.
linksobject[]Required. Attached short links with slug, alias, and destination URL.
links[].slugstringRequired. Public slug of the attached link.
links[].aliasstring | nullRequired. Custom back-half, or null.
links[].urlstringRequired. Destination URL.
startsAtstring | nullRequired. ISO 8601 start, or null.
endsAtstring | nullRequired. ISO 8601 end, or null.
createdAtstringRequired. ISO 8601 time the campaign was created.

Errors

StatusErrorDescription
400Bad RequestValidation failed, a slug is unknown, or a template rule was broken.
401UnauthorizedMissing, malformed, or invalid Bearer token.
403ForbiddenCampaigns are not available on the current plan.
429Too Many RequestsMore than 10 requests per minute and 50 requests per day. Some responses include a Retry-After header.
500Internal Server ErrorUnexpected server error. Retry the request.