DEV Community

Cover image for I Automated My Entire Link Management Workflow with a URL Shortener API — Here's How
Muhammad Jahangeer Shams
Muhammad Jahangeer Shams

Posted on

I Automated My Entire Link Management Workflow with a URL Shortener API — Here's How

#api #webdev #javascript #productivity

Most developers I know treat URL shorteners as a throwaway tool. Paste a link, get a short one, move on. I used to think the same until I started building out a proper content and campaign workflow and realized how much I was doing manually that an API could handle for me.

This post walks through what HitURL can actually do from a developer's perspective including things most people completely ignore, like pixel firing through short links, dynamic QR codes, and geo/device targeting per link. All accessible via a clean REST API.

The problem with manual link management at scale

When you're running one campaign, manually creating short links is fine. When you're running ten campaigns across social, email, and print simultaneously, each needing its own tracking pixel, geo target, custom alias, and QR code, it becomes a mess fast.

The fix isn't a fancier UI. It's an API that lets you create and manage everything programmatically as part of your deployment pipeline.

Getting started with the HitURL API

Every registered account gets an API key automatically. Authentication is Bearer token straightforward:

curl --location --request GET 'https://hiturl.at/api/account' \
--header 'Authorization: Bearer YOURAPIKEY' \
--header 'Content-Type: application/json'
Enter fullscreen mode Exit fullscreen mode

The rate limit is 30 requests per minute, with limit headers returned on every response so you can manage backoff:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: TIMESTAMP
Enter fullscreen mode Exit fullscreen mode

All responses are JSON. Error handling is consistent check the error key first, then proceed:

{
  "error": 0,
  "data": { ... }
}
Enter fullscreen mode Exit fullscreen mode

Shortening a link and everything you can attach to it

The basic shorten endpoint is POST /api/url/add. But what makes it interesting is the payload. This isn't just a URL-in, short-URL-out operation. Here's a fuller example:

const response = await fetch('https://hiturl.at/api/url/add', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOURAPIKEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://yoursite.com/landing',
    custom: 'spring-launch',
    pixels: [1, 2],          // fire tracking pixels on click
    channel: 3,               // assign to a channel for organization
    campaign: 1,              // attach to a campaign
    geotarget: [              // redirect by country
      { location: 'Canada', link: 'https://yoursite.com/ca' },
      { location: 'United States', link: 'https://yoursite.com/us' }
    ],
    devicetarget: [           // redirect by device
      { device: 'iPhone', link: 'https://apps.apple.com/yourapp' },
      { device: 'Android', link: 'https://play.google.com/yourapp' }
    ],
    expiry: '2025-12-31 23:59:59',
    status: 'public'
  })
});

const data = await response.json();
console.log(data.shorturl); // https://hiturl.at/spring-launch
Enter fullscreen mode Exit fullscreen mode

That single API call creates a short link that: fires tracking pixels on click, routes Canadian visitors to the Canadian landing page, routes iOS/Android users to the correct app store, and expires automatically at year end. That's a lot of campaign logic in one request.

The pixel system retargeting through short links

This is the feature most people don't know about. HitURL lets you attach retargeting pixels to short links so anyone who clicks your link gets added to your ad audiences automatically, without ever visiting a page you own.

It supports: Facebook Pixel, Google Ads conversion, LinkedIn Insight Tag, Twitter/X Pixel, AdRoll, Quora Pixel, and Google Tag Manager (which lets you bundle multiple pixels into one).

Setting up a pixel via the API:

import requests

url = "https://hiturl.at/api/pixel/add"
payload = {
    "type": "facebook",
    "name": "Main FB Pixel",
    "tag": "YOUR_PIXEL_ID"
}
headers = {
    'Authorization': 'Bearer YOURAPIKEY',
    'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)
Enter fullscreen mode Exit fullscreen mode

Once created, you get back a pixel ID. Then you pass that ID in the pixels array when shortening any link. Every click on that short link now fires the pixel whether the click comes from a tweet, a newsletter, a QR code scan, or a direct message.

This is genuinely useful for cold traffic retargeting. You can share a link anywhere, and anyone who clicks automatically enters your remarketing pool, even if they never reach your own domain.

QR codes dynamic, branded, and trackable

QR codes have had a major resurgence and they're now a serious campaign channel, not just a novelty. The key distinction is static vs. dynamic:

  • Static QR code destination URL is baked into the code. Change the destination = reprint everything.
  • Dynamic QR code points to a short link. Change the destination URL any time without touching the printed code. HitURL generates dynamic, trackable QR codes via API: 
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => "https://hiturl.at/api/qr/add",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOURAPIKEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "link" => "https://hiturl.at/spring-launch",
        "type" => "link"
    ])
));
$response = curl_exec($curl);
Enter fullscreen mode Exit fullscreen mode

What you get back is a QR code tied to your short link. It tracks every scan the same way clicks are tracked device, location, referrer. And since it points to a dynamic short link, you can update the destination post-print if your campaign page changes or goes down.

Three things worth knowing from the help docs:

Gradient and branded QR codes are supported. You can apply your brand colors including gradient styles directly to the QR code. This matters for print collateral where a black-and-white generic QR looks out of place next to branded design.

Custom logos can be embedded in the center. Standard practice for branded QR codes at this point, but worth confirming the API supports it if you're building this into a pipeline.

Matrix and eye styles are customizable. The individual modules (dots vs. squares) and corner eyes can be styled. Minor detail, but relevant if you're generating QR codes at scale and want visual consistency across materials.

Link-in-bio pages not just for influencers

The link-in-bio concept started with Instagram and TikTok, where you get one link in your profile. But the use case extends to any context where you need a single URL to surface multiple destinations.

From the help docs, HitURL's bio page feature is designed for artists, creators, and anyone managing multiple active links from a single profile URL. The practical setup:

Instagram go to Edit Profile, paste your hiturl.at/yourbio URL in the website field. One URL, multiple links displayed on a clean mobile-optimized page.

TikTok requires 1,000+ followers to add a link. Same flow: replace the website field with your bio page URL.

The API includes bio page items in the channel/item system. You can list, assign, and manage bio page links programmatically the same way you manage short links:

# list items in a channel (includes both links and bio pages)
curl --location --request GET 'https://hiturl.at/api/channel/1?limit=10&page=1' \
--header 'Authorization: Bearer YOURAPIKEY' \
--header 'Content-Type: application/json'
Enter fullscreen mode Exit fullscreen mode

Response includes item type (links or bio), making it easy to filter programmatically.

Organizing at scale channels and campaigns

Two concepts worth understanding if you're managing links across multiple projects:

Channels are organizational containers color-coded, star-able, and searchable. Think of them as folders. You assign links, bio pages, and QR codes to channels to keep your dashboard from becoming a flat list of hundreds of items.

Campaigns are for grouping links by marketing objective and enabling campaign rotators a single short URL that distributes traffic across multiple destination URLs. Useful for A/B testing landing pages or load-balancing traffic across variations.

Creating a campaign rotator:

import requests

# create the campaign
campaign = requests.post(
    'https://hiturl.at/api/campaign/add',
    headers={'Authorization': 'Bearer YOURAPIKEY', 'Content-Type': 'application/json'},
    json={
        'name': 'Spring A/B Test',
        'slug': 'spring-ab',
        'public': False
    }
).json()

campaign_id = campaign['id']

# assign links to the campaign
for link_id in [101, 102, 103]:
    requests.post(
        f'https://hiturl.at/api/campaign/{campaign_id}/assign/{link_id}',
        headers={'Authorization': 'Bearer YOURAPIKEY', 'Content-Type': 'application/json'}
    )
Enter fullscreen mode Exit fullscreen mode

The campaign rotator URL distributes clicks across all assigned links no client-side logic needed.

A practical automation pattern: campaign launch script

Here's a minimal pattern for creating a complete campaign setup in one script short link + pixel attachment + QR code + campaign assignment:

const API = 'https://hiturl.at/api';
const HEADERS = {
  'Authorization': 'Bearer YOURAPIKEY',
  'Content-Type': 'application/json'
};

async function createCampaignBundle({ name, slug, destinationUrl, pixelIds, geoTargets }) {
  // 1. Create the short link
  const linkRes = await fetch(`${API}/url/add`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({
      url: destinationUrl,
      custom: slug,
      pixels: pixelIds,
      geotarget: geoTargets,
      status: 'public'
    })
  });
  const link = await linkRes.json();
  const shortUrl = link.shorturl;

  // 2. Generate a QR code for the short link
  const qrRes = await fetch(`${API}/qr/add`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({ link: shortUrl, type: 'link' })
  });
  const qr = await qrRes.json();

  // 3. Create a campaign and assign the link
  const campaignRes = await fetch(`${API}/campaign/add`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({ name, slug, public: false })
  });
  const campaign = await campaignRes.json();

  await fetch(`${API}/campaign/${campaign.id}/assign/${link.id}`, {
    method: 'POST',
    headers: HEADERS
  });

  return {
    shortUrl,
    qrCodeId: qr.id,
    campaignId: campaign.id,
    rotatorUrl: campaign.rotator
  };
}
Enter fullscreen mode Exit fullscreen mode

Call this once per campaign and you get back everything you need to wire into your deployment scripts, CMS, or notification system.

API quick reference

Endpoint Method Description
/api/url/add POST Shorten a link with full targeting options
/api/url/:id GET Get single link with click analytics
/api/url/:id/update PUT Update destination, expiry, pixels
/api/url/:id/delete DELETE Delete a link
/api/pixels GET List tracking pixels
/api/pixel/add POST Create a new tracking pixel
/api/qr/add POST Generate a QR code
/api/qr/:id/update PUT Update QR code
/api/campaign/add POST Create a campaign
/api/campaign/:id/assign/:linkid POST Add link to campaign
/api/channel/add POST Create an organizational channel
/api/domains GET List branded domains
/api/domain/add POST Add a custom branded domain

Rate limit: 30 req/min. Auth: Bearer token. All responses: JSON.

Wrapping up

Most URL shorteners stop at "give me a short URL." What's useful for developers is the layer on top pixels, geo targeting, device routing, QR codes, campaign grouping all accessible via a clean API so you can wire it into whatever you're building.

The full API docs are at hiturl.at/developers if you want to explore the complete endpoint reference. The help center at hiturl.at/help covers the pixel setup guides (Facebook, Google, LinkedIn, AdRoll, Quora, GTM) and QR code customization in more detail.

Have a link management or campaign automation pattern you're using? Drop it in the comments always curious how other devs are handling this.

Top comments (0)