Skip to main content
POST
/
v2
/
links
curl -X POST https://app.tracklysms.com/api/v2/links \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "offerId": "6789abcd1234ef5678901234",
    "listId": 42
  }'

{
  "shortUrl": "https://yourdomain.com/Ab3kX9",
  "linkId": "Ab3kX9",
  "clickTrackerUrl": "https://ct.yourdomain.click/c/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "destinationUrl": "https://example.com/offer?aff_sub={{sendId}}",
  "domain": "https://yourdomain.com",
  "offerId": "6789abcd1234ef5678901234"
}
Create a trackable short link that routes through your click tracker to an offer destination URL. The short link uses your list’s configured link shortener domain, and the click tracker uses your list’s click tracking domain (or the platform fallback).
Requires Offer Management. This endpoint is only available to accounts with the Offer Management product enabled. Returns 403 product_not_enabled otherwise.

​
How It Works

When a recipient clicks the short link, the redirect chain is: 
Short link (list domain) → Click tracker (list domain) → Offer destination URL
  1. The short link (shortUrl) goes in your SMS message body
  2. On click, it redirects through the click tracker (clickTrackerUrl) which records the click
  3. The click tracker redirects to the offer’s destination URL

​
Body Parameters

​
offerId
string
Internal partnership offer ID. Required if externalOfferId is not provided.
​
externalOfferId
string
External platform offer ID (e.g. TUNE/HasOffers ID). Required if offerId is not provided. If both are provided, offerId takes priority.
​
listId
integer
Sending list ID. Required if phoneNumber is not provided. The list determines which link shortener and click tracking domains are used.
​
phoneNumber
string
Sending list phone number in E.164 format (e.g. +18005551234). Required if listId is not provided. Alternative way to identify the sending list.

​
Response Fields

​
shortUrl
string
Full short URL to include in your SMS message body. Uses the list’s configured link shortener domain.
​
linkId
string
Unique short link ID. Appended to the domain to form the shortUrl.
​
clickTrackerUrl
string
The click tracker URL that the short link redirects through. Records the click before forwarding to the offer destination.
​
destinationUrl
string
The offer’s final destination URL that the recipient lands on after click tracking.
​
domain
string
The link shortener domain used for this short link.
​
offerId
string
The internal partnership offer ID the link is associated with.

​
Examples

curl -X POST https://app.tracklysms.com/api/v2/links \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "offerId": "6789abcd1234ef5678901234",
    "listId": 42
  }'

​
Using External Offer ID and Phone Number

curl -X POST https://app.tracklysms.com/api/v2/links \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOfferId": "12345",
    "phoneNumber": "+18005551234"
  }'

{
  "shortUrl": "https://yourdomain.com/Ab3kX9",
  "linkId": "Ab3kX9",
  "clickTrackerUrl": "https://ct.yourdomain.click/c/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "destinationUrl": "https://example.com/offer?aff_sub={{sendId}}",
  "domain": "https://yourdomain.com",
  "offerId": "6789abcd1234ef5678901234"
}

​
Error Codes

HTTP StatusError CodeDescription
400missing_offer_idNeither offerId nor externalOfferId was provided.
400missing_list_identifierNeither listId nor phoneNumber was provided.
400invalid_phoneThe phoneNumber field is not a valid E.164 phone number.
403product_not_enabledYour account does not have the Offer Management product enabled.
404offer_not_foundNo active partnership offer found matching the provided ID.
404list_not_foundThe sending list was not found or does not belong to your account.
409no_domain_configuredThe sending list does not have a link shortener domain configured. Assign a domain in your list settings first.
500id_collisionFailed to generate a unique link ID after multiple attempts. Retry the request.

​
Macros & URL Parameters

The click tracker supports macros — placeholder tokens in your offer’s Destination URL Template that get replaced with real values at click time. You can configure the Destination URL Template on your offer in the UI (under Offer Management > Offers).

​
Supported Macros

Use these in your Destination URL Template with curly brace syntax (e.g. {click_id}):
MacroDescription
{click_id}Unique click identifier
{transaction_id}Alias for {click_id} (HasOffers terminology)
{affiliate_id}Affiliate identifier
{offer_id}Offer identifier
{account_id}Account identifier
{sub1} – {sub5}Sub-tracking parameters passed on the short link URL
{source}Traffic source identifier
{creative}Creative identifier
{cost}Cost value
{ip}Visitor’s IP address
{user_agent}Visitor’s user agent string
{datetime}Click timestamp (ISO 8601)
{country_code}Visitor’s country code (from GeoIP)

​
Example Destination URL Template

https://example.com/lp?clickid={click_id}&aff={affiliate_id}&s1={sub1}&s2={sub2}
If no macros are present in the template, click_id and any sub-tracking parameters are automatically appended as query parameters. Any query parameters appended to the short link URL at click time are forwarded through the click tracker and used to populate macros. This lets you pass dynamic per-recipient values without creating separate links. For example, if your short link is https://yourdomain.com/Ab3kX9, you can append parameters in the SMS body: 
https://yourdomain.com/Ab3kX9?sub1=campaign_a&sub2=user_123&source=sms
The click tracker picks up sub1, sub2, and source from the query string, substitutes them into the Destination URL Template macros, and redirects the visitor to the final URL with all values filled in. This means you can create one link per offer/list combination and personalize it per message by appending query parameters in your message body.

​
Notes

  • The offer must be active (status: 'active') to create links.
  • The sending list must be active and have a link shortener domain configured in its settings.
  • If the list has a custom click tracking domain configured, it will be used. Otherwise, the platform’s default click tracker is used.
  • Each call creates a new unique short link. There is no deduplication — calling this endpoint twice with the same parameters produces two different links.

​
Next Steps

Link Tracking

Track clicks and attribute conversions

Create Offer

Set up an offer before creating links