API
Already run your own system and only need the short links? Make tracking links, read every click, pull stats and report sales over a plain JSON API. Links made through the API are the same as dashboard links: bot filtering, rotators, custom domains and backup links all apply.
Basics
- Base URL:
https://hoplytic.com/api/v1 - Make a key on the API page of your dashboard, and send it with every request:
Authorization: Bearer trk_… - Bodies are JSON (
Content-Type: application/json). Times are UTC, ISO 8601. - Limit: 600 requests a minute per key. Over it you get
429with aRetry-Afterheader. - Errors look like
{"error": {"code": "invalid", "message": "…"}}with status 400, 401, 404, 409, 413, 415 or 429. - The redirect itself never calls the API and never waits for it. Your links keep working even if your system is down.
Links
POST/links
Makes a short link. Only url is required.
url | Where the link goes: an affiliate link or any page. Up to 2,000 characters. |
network | auto (default): we recognise the network and put our click ID in its sub-ID field. none: your URL is used exactly as given. Or a network id from GET /networks. |
sub_ids | Optional. Exactly which parameters to set, e.g. {"clickref": "{click_id}", "sub2": "{q:site}"}. |
source | Optional ad platform id (e.g. taboola, propellerads): its macros are added to the tracking link. |
code | Optional short code (letters, numbers, - and _). Random if left out. |
domain | Optional: one of your verified custom domains, e.g. go.yoursite.com. |
name | Optional label. |
fallback_url | Optional backup link, used when the destination stops working (checked every 30 minutes). |
forward_query | Optional, true passes any extra parameters on the short link through to the destination. |
Placeholders you can use in url (with network: "none") or in sub_ids: {click_id} (our unique ID for each click; send it to the network so sales come back to the right click), {country}, {device}, {link}, {ts}, and {q:name} for the value of ?name= on the short link.
curl -X POST https://hoplytic.com/api/v1/links \
-H "Authorization: Bearer trk_..." -H "Content-Type: application/json" \
-d '{"url": "https://shop.example.com/product?ref=me&subid={click_id}", "network": "none", "code": "spring-sale"}'201 Created
{
"id": "6f1c…", "code": "spring-sale", "short_url": "https://vitalverify.click/spring-sale",
"destination": "https://shop.example.com/product?ref=me&subid={click_id}",
"network": "custom", "fallback_url": null, "destination_health": "unknown", "archived": false,
"created_at": "2026-11-17T09:30:00.000Z", "warnings": []
}GET/links
Your links, newest first. ?limit= up to 500 (default 100); pass next_cursor back as ?cursor= for the next page. ?archived=true includes archived links.
GET/links/{id or code}
One link, with its rotation offers if it has any. A code means a link on the shared domain; add ?domain=go.yoursite.com for a custom domain.
PATCH/links/{id or code}
Change name, url (used exactly as given), fallback_url (null removes it) or forward_query. Changes reach every redirect server within a second.
curl -X PATCH https://hoplytic.com/api/v1/links/spring-sale -H "Authorization: Bearer trk_..." -H "Content-Type: application/json" -d '{"fallback_url": "https://shop.example.com/"}'DELETE/links/{id or code}
Archives the link: it stops redirecting, its stats stay.
GET/links/{id or code}/stats
People, bots and suspicious clicks per day, top countries and devices, and sales. ?days= 1 to 400 (default 30).
Clicks
GET/clicks
Every stored click, oldest first, with country, device, browser, referrer, bot labels and all the parameters it arrived with. Filters: since, until, link (id or code), bots=false, limit (up to 5,000). Without since you get the last 7 days.
Keeping your own copy in sync: save next_cursor and call again with ?after= it. You get only newer clicks, never one twice. Clicks show up here about 30 seconds after they happen.
{
"data": [{
"click_id": "mwjsoz20a9eba3cf44", "link_id": "6f1c…", "clicked_at": "2026-11-17T09:31:12.481Z",
"country": "US", "device": "mobile", "os": "iOS", "browser": "Safari", "referer_host": "www.reddit.com",
"is_bot": false, "bot_reason": null, "suspect_reason": null, "network_org": "Comcast Cable",
"rotation_offer_id": null, "params": {"utm_source": "reddit", "site": "pub7"}
}],
"next_cursor": "48213", "has_more": false
}GET/clicks/{click_id}
One click by our click ID, for example when a sale arrives in your system carrying it.
Sales
POST/conversions
Report a sale or lead: click_id, payout, and optionally currency (default USD), status (approved, pending, rejected) and txid. Sending the same txid again updates the sale instead of adding one. Send up to 500 at once as {"conversions": [ … ]}. Networks can also call your postback URL directly; see the Postback page.
curl -X POST https://hoplytic.com/api/v1/conversions -H "Authorization: Bearer trk_..." -H "Content-Type: application/json" -d '{"click_id": "mwjsoz20a9eba3cf44", "payout": 12.50, "currency": "EUR", "txid": "order-1043"}'Account
GET/usage
This month's tracked clicks, your free allowance, and what the month would cost after the launch period.
GET/networks
Network and ad platform ids for network and source, with their sub-ID fields and macros. No key needed.