Skip to main content
POST
/
v2
/
links
/
shorten
curl -X POST https://api.tracklysms.com/api/v2/links/shorten \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/landing-page",
    "listId": 42
  }'

{
  "shortUrl": "https://yourdomain.com/Ab3kX9q",
  "linkId": "Ab3kX9q",
  "destinationUrl": "https://example.com/offer?aff_sub=12345",
  "domain": "yourdomain.com",
  "offerId": "6651a3ef1234567890abcdef",
  "filterBots": false
}

Documentation Index

Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt

Use this file to discover all available pages before exploring further.

Create a trackable short link for any URL or an offer from your catalog. Unlike POST /v2/links (which requires Offer Management and only supports PartnershipOffers), this endpoint works with any URL and with SMS Offers.
Requires SMS product. This endpoint is available to any account with the SMS product enabled. Returns 403 product_not_enabled otherwise.

​
How It Works

There are two modes:
  1. URL mode — provide a raw url and get a short link pointing directly at it. No affiliate tracking.
  2. Offer mode — provide an offerId (from your SMS Offers, not PartnershipOffers) and the endpoint resolves the offer’s tracking URL with proper TUNE/Everflow parameters, preserving affiliate attribution.
When a recipient clicks the short link: 
Short link (list domain) -> Link tracking service -> Destination URL

​
Body Parameters

​
url
string
Raw destination URL to shorten. Must use http or https scheme. Required unless offerId is provided.
​
offerId
string
SMS Offer ID (from the offers collection). If provided, the endpoint resolves the offer’s tracking URL with proper TUNE/Everflow params. Takes priority over url if both are provided.
​
listId
integer
Sending list ID — determines which shortener domain to use. Required unless phoneNumber is provided.
​
phoneNumber
string
Sending list phone number in E.164 format (e.g. +18005551234). Alternative to listId. Required unless listId is provided.
​
contactPhone
string
Contact phone number in E.164 format. Passed as a macro to offer URL templates ({{contact.phone}}). Optional.
​
metadata
object
Arbitrary key-value pairs stored on the short link for attribution. For example, {"source": "ai_agent", "conversation_id": "abc123"}. Optional.

​
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.
​
destinationUrl
string
The final destination URL that the recipient lands on after redirect.
​
domain
string
The link shortener domain used for this short link.
​
offerId
string
The SMS offer ID the link is associated with, if an offer was used.
​
filterBots
boolean
Whether bot filtering is enabled for this link. Inherited from the offer’s filter_bots setting when offerId is provided.

​
Examples

​
Shorten a raw URL

curl -X POST https://api.tracklysms.com/api/v2/links/shorten \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/landing-page",
    "listId": 42
  }'

curl -X POST https://api.tracklysms.com/api/v2/links/shorten \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "offerId": "6651a3ef1234567890abcdef",
    "phoneNumber": "+18005551234",
    "contactPhone": "+15551234567",
    "metadata": {
      "source": "ai_agent",
      "conversation_id": "conv_abc123"
    }
  }'

{
  "shortUrl": "https://yourdomain.com/Ab3kX9q",
  "linkId": "Ab3kX9q",
  "destinationUrl": "https://example.com/offer?aff_sub=12345",
  "domain": "yourdomain.com",
  "offerId": "6651a3ef1234567890abcdef",
  "filterBots": false
}

​
Error Codes

HTTP StatusError CodeDescription
400missing_url_or_offerNeither url nor offerId was provided.
400missing_list_identifierNeither listId nor phoneNumber was provided.
400invalid_urlThe url does not use http or https scheme.
400invalid_phoneThe phoneNumber is not a valid E.164 phone number.
403product_not_enabledYour account does not have the SMS product enabled.
404offer_not_foundNo active offer found matching the provided offerId.
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.
500id_collisionFailed to generate a unique link ID after multiple attempts. Retry the request.

​
Notes

  • The metadata field is stored on the MessageShortLink document and can be used for attribution tracking in analytics.
  • When offerId is provided, the offer’s filter_bots setting is inherited by the short link. The link tracking service handles bot filtering on click.
  • Each call creates a new unique short link. There is no deduplication.
  • This endpoint is separate from POST /v2/links, which continues to serve PartnershipOffers only.

​
Next Steps

Create Link (Offers)

Create links for partnership offers

Link Tracking

Track clicks and attribute conversions