Update Tracking Link (v1)

Method & Path

PATCH /api/v1/workspace/:workspaceId/tracking-links/:linkId

Description

Update an existing tracking link. All fields are optional - only provided fields will be updated.

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
linkId	string	Yes	Tracking link identifier

Query Parameters

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

Request Body

{
  "name": "Updated Campaign Name",
  "isActive": false
}

Request Body Schema

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

Response 200 OK

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

Common Errors

400 Bad Request: Invalid request body (e.g., 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, tracking link, or destination not found

409 Conflict: Tracking link with same utmName and destinationSlug already exists (if updating utmName or destinationSlug)

422 Unprocessable Entity: Validation error

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

Notes

• At least one field must be provided in the request body
• Updating utmName or destinationSlug requires uniqueness check
• fullUrl is only included in response if baseUrl query parameter is provided