Create Tracking Link (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/tracking-links

Description

Create a new tracking link for a vCard or storefront.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with workspace.settings.manage permission.

Headers

Authorization: Bearer <workspace_token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

Parameter	Type	Required	Description
baseUrl	string	No	Base URL for generating full tracking link (must be valid URL)

Request Body

{
  "type": "vcard",
  "name": "Facebook Campaign",
  "utmName": "facebook-campaign",
  "destinationSlug": "my-vcard",
  "isActive": true
}

Request Body Schema

Field	Type	Required	Description
type	string	Yes	Link type (vcard, storefront)
name	string	Yes	Human-readable link name (min: 1, max: 120 characters)
utmName	string	Yes	UTM parameter name (min: 1, max: 100 characters)
destinationSlug	string	Yes	Slug of the destination vCard or storefront (min: 1, max: 120 characters)
isActive	boolean	No	Whether the link is active (default: true)

Response 201 Created

{
  "link": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439012",
    "type": "vcard",
    "name": "Facebook Campaign",
    "utmName": "facebook-campaign",
    "destinationSlug": "my-vcard",
    "isActive": true,
    "fullUrl": "https://example.com/vcard/my-vcard?utm_source=facebook-campaign",
    "createdAt": "2024-12-01T10:00:00.000Z",
    "updatedAt": "2024-12-01T10:00:00.000Z"
  }
}

Common Errors

400 Bad Request: Invalid request body (e.g., missing required fields, invalid type, invalid slug)

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: User does not have workspace.settings.manage permission

404 Not Found: Workspace or destination (vCard/storefront) not found

409 Conflict: Tracking link with same utmName and destinationSlug already exists

422 Unprocessable Entity: Validation error (e.g., invalid slug format)

500 Internal Server Error: Server error occurred while processing the request

Notes

• utmName must be unique per workspace and destination combination
• destinationSlug must reference an existing vCard or storefront
• fullUrl is only included in response if baseUrl query parameter is provided
• Workspace subscription status is checked before processing the request