Links API

Create a link

POST /v1/links

Create a trackable short link with an optional deep link payload.

Request body

{
  "deepLinkPath": "/product/123",
  "deepLinkParams": {"color": "blue"},
  "campaignId": "summer_sale",
  "iosDestination": "https://apps.apple.com/app/myapp/id123456",
  "androidDestination": "https://play.google.com/store/apps/details?id=com.example",
  "fallbackUrl": "https://myapp.com/product/123",
  "metadata": {"created_by": "api"},
  "expiresInDays": 30,
  "sandbox": false
}

Field	Type	Required	Description
`deepLinkPath`	string	yes	Path delivered to the app (e.g. `/product/123`)
`deepLinkParams`	object	no	Key-value pairs delivered alongside the path
`campaignId`	string	no	Campaign identifier for attribution grouping
`iosDestination`	string	no	App Store URL for iOS users
`androidDestination`	string	no	Play Store URL for Android users
`fallbackUrl`	string	no	URL for users on unsupported platforms
`metadata`	object	no	Arbitrary key-value metadata stored with the link
`expiresInDays`	int	no	Link expires after this many days
`sandbox`	boolean	no	If `true`, only debug builds can claim clicks from this link

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "shortCode": "abc123",
  "shortUrl": "https://yourapp.traceclick.io/l/abc123",
  "deepLinkPath": "/product/123",
  "deepLinkParams": {"color": "blue"},
  "campaignId": "summer_sale",
  "iosDestination": "https://apps.apple.com/app/myapp/id123456",
  "androidDestination": "https://play.google.com/store/apps/details?id=com.example",
  "fallbackUrl": "https://myapp.com/product/123",
  "metadata": {"created_by": "api"},
  "sandbox": false,
  "expiresAt": "2024-08-15T00:00:00Z",
  "createdAt": "2024-07-15T12:00:00Z",
  "updatedAt": "2024-07-15T12:00:00Z"
}

Example

curl -X POST https://api.traceclick.io/v1/links \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "deepLinkPath": "/invite/summer",
    "campaignId": "summer_sale",
    "fallbackUrl": "https://myapp.com"
  }'

List links

GET /v1/links

List all links for your app. Supports pagination and campaign filtering.

Query parameters

Parameter	Type	Default	Description
`campaignId`	string	—	Filter by campaign ID
`limit`	int	50	Max results (1-100)
`offset`	int	0	Pagination offset

Response

[
  {
    "id": "...",
    "shortCode": "abc123",
    "shortUrl": "https://yourapp.traceclick.io/l/abc123",
    "deepLinkPath": "/invite/summer",
    "campaignId": "summer_sale",
    "createdAt": "2024-07-15T12:00:00Z"
  }
]

Example

# List all links for a campaign
curl "https://api.traceclick.io/v1/links?campaignId=summer_sale&limit=10" \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx"

Get a link

GET /v1/links/{shortCode}

Retrieve details of a specific link by its short code.

Example

curl https://api.traceclick.io/v1/links/abc123 \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx"

Update a link

PATCH /v1/links/{shortCode}

Update any field on an existing link. Only include the fields you want to change.

Request body

{
  "deepLinkPath": "/product/456",
  "campaignId": "winter_sale",
  "expiresInDays": 60
}

All fields from the create request are accepted. The shortCode cannot be changed.

Example

curl -X PATCH https://api.traceclick.io/v1/links/abc123 \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"campaignId": "winter_sale"}'

Delete a link

DELETE /v1/links/{shortCode}

Soft-delete a link. The short code becomes inactive and stops redirecting.

Example

curl -X DELETE https://api.traceclick.io/v1/links/abc123 \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx"