Skip to main content

​
Overview

Campaigns allow you to group links under specific marketing initiatives or time periods. Each campaign must be associated with a client and can contain multiple links.
All endpoints require authentication via Bearer token in the Authorization header.

​
List Campaigns

​
Query Parameters

​
clientId
string
Filter campaigns by client UUID.

​
Response

​
id
string
Unique identifier (UUID) of the campaign.
​
name
string
Name of the campaign.
​
clientId
string
UUID of the associated client.
​
clientName
string
Name of the associated client.
​
linksCount
number
Number of links associated with this campaign.
​
createdAt
string
ISO 8601 timestamp of creation.
​
updatedAt
string
ISO 8601 timestamp of last update.

​
Example Request

curl -X GET "https://api.example.com/campaigns?clientId=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

[
  {
    "id": "987fcdeb-51a2-43d7-b890-123456789abc",
    "name": "Spring 2026",
    "clientId": "123e4567-e89b-12d3-a456-426614174000",
    "clientName": "Acme Corp",
    "linksCount": 45,
    "createdAt": "2026-02-01T10:00:00.000Z",
    "updatedAt": "2026-02-01T10:00:00.000Z"
  },
  {
    "id": "876edcba-12a3-34d5-c678-901234567def",
    "name": "Summer Sale",
    "clientId": "123e4567-e89b-12d3-a456-426614174000",
    "clientName": "Acme Corp",
    "linksCount": 32,
    "createdAt": "2026-03-01T14:30:00.000Z",
    "updatedAt": "2026-03-01T14:30:00.000Z"
  }
]

​
Create Campaign

​
Request Body

​
name
string
required
Name of the campaign. Must be at least 3 characters long.
​
clientId
string
required
UUID of the client this campaign belongs to. Client must exist in the system.
Campaign names must be unique within each client. You can have campaigns with the same name across different clients.

​
Response

​
id
string
Unique identifier (UUID) of the created campaign.
​
name
string
Name of the campaign.
​
clientId
string
UUID of the associated client.
​
createdAt
string
ISO 8601 timestamp of creation.
​
updatedAt
string
ISO 8601 timestamp of last update.

​
Example Request

curl -X POST https://api.example.com/campaigns \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fall Campaign 2026",
    "clientId": "123e4567-e89b-12d3-a456-426614174000"
  }'

​
Example Response

{
  "id": "765dcba9-01b2-23c4-d567-890123456fed",
  "name": "Fall Campaign 2026",
  "clientId": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-03-09T10:30:00.000Z",
  "updatedAt": "2026-03-09T10:30:00.000Z"
}

​
Error Responses

​
404
object
Client not found.
{
  "message": "Client not found"
}
​
409
object
Campaign with this name already exists for this client.
{
  "message": "Campaign already exists for this client"
}

​
Get Campaign

​
Path Parameters

​
id
string
required
UUID of the campaign to retrieve.

​
Response

​
id
string
Unique identifier (UUID) of the campaign.
​
name
string
Name of the campaign.
​
clientId
string
UUID of the associated client.
​
createdAt
string
ISO 8601 timestamp of creation.
​
updatedAt
string
ISO 8601 timestamp of last update.

​
Example Request

curl -X GET https://api.example.com/campaigns/987fcdeb-51a2-43d7-b890-123456789abc \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "id": "987fcdeb-51a2-43d7-b890-123456789abc",
  "name": "Spring 2026",
  "clientId": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-02-01T10:00:00.000Z",
  "updatedAt": "2026-02-01T10:00:00.000Z"
}

​
Error Responses

​
404
object
Campaign not found.
{
  "message": "Campaign not found"
}

​
Update Campaign

​
Path Parameters

​
id
string
required
UUID of the campaign to update.

​
Request Body

​
name
string
required
Updated name for the campaign. Must be at least 3 characters long.
The updated name must be unique within the campaign’s client.

​
Response

Returns the updated campaign object with the same structure as the Get Campaign response.

​
Example Request

curl -X PUT https://api.example.com/campaigns/987fcdeb-51a2-43d7-b890-123456789abc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring 2026 - Extended"
  }'

​
Example Response

{
  "id": "987fcdeb-51a2-43d7-b890-123456789abc",
  "name": "Spring 2026 - Extended",
  "clientId": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-02-01T10:00:00.000Z",
  "updatedAt": "2026-03-09T10:30:00.000Z"
}

​
Error Responses

​
404
object
Campaign not found.
{
  "message": "Campaign not found"
}
​
409
object
Another campaign with this name already exists for this client.
{
  "message": "Campaign already exists for this client"
}

​
Delete Campaign

​
Path Parameters

​
id
string
required
UUID of the campaign to delete.

​
Response

Returns 204 No Content on success.

​
Example Request

curl -X DELETE https://api.example.com/campaigns/987fcdeb-51a2-43d7-b890-123456789abc \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Error Responses

​
404
object
Campaign not found.
{
  "message": "Campaign not found"
}
Deleting a campaign does NOT delete the associated links. Links will have their campaignId set to null after the campaign is deleted.

Build docs developers (and LLMs) love

Get started for freeTalk to us