List Tracking Links (v1)

Method & Path

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

Description

Retrieve all tracking links for a workspace with optional filtering by type.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with workspace.read 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
type	string	No	Filter by link type (vcard, storefront)
baseUrl	string	No	Base URL for generating full tracking links (must be valid URL)

Response 200 OK

{
  "links": [
    {
      "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"
    }
  ]
}

Response Fields

• id (string): Tracking link identifier
• workspaceId (string): Workspace identifier
• type (string): Link type (vcard, storefront)
• name (string): Human-readable link name
• utmName (string): UTM parameter name (used in URL as utm_source)
• destinationSlug (string): Slug of the destination (vCard or storefront)
• isActive (boolean): Whether the link is active
• fullUrl (string | null): Complete tracking URL (only if baseUrl query parameter provided)
• createdAt (string): Creation timestamp (ISO 8601 format)
• updatedAt (string): Last update timestamp (ISO 8601 format)

Common Errors

400 Bad Request: Invalid query parameters (e.g., invalid baseUrl format)

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: User does not have workspace.read permission

404 Not Found: Workspace not found

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

Notes

• If baseUrl is provided, fullUrl will be generated for each link
• Links are sorted by creation date (newest first)
• Only active links are recommended for sharing