Short Links API

Branded short URLs for messages and campaigns. By default links resolve on the platform host (https://api.orbit.devotel.io/l/abc123); configure a vanity domain in Settings → General to mint links on your own host instead (e.g. https://go.yourbrand.com/abc123). The redirect handler (GET /l/:code) is mounted at the root of the API host and is rate-limited to 60 req/min per IP. Click data is captured asynchronously and exposed via the stats endpoint. Base path: /api/v1/links (management) — public redirect at https://api.orbit.devotel.io/l/{code} Authentication: API key (X-API-Key) or session JWT for management; the redirect itself is anonymous. Envelope: Like every management endpoint, responses are wrapped as { "data": { … }, "meta": { "request_id": "…", "timestamp": "…" } }. The examples below show the data payload.

Method	Path	Purpose
`POST`	`/api/v1/links/`	Create a short link
`GET`	`/api/v1/links/`	List short links
`GET`	`/api/v1/links/insights`	Tenant-wide insights — summary KPIs, top links, daily click timeline
`GET`	`/api/v1/links/campaigns/{campaignId}/link-analytics`	Per-campaign link-click attribution rollup
`GET`	`/api/v1/links/contacts/{contactId}/clicks`	Per-contact link-click history
`GET`	`/api/v1/links/{id}/stats`	Per-link click stats
`DELETE`	`/api/v1/links/{id}`	Delete a short link

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.links.list();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/links")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Default short-link host & branded domains

Every short link resolves through the redirect handler at GET /l/{code}. The host a link is minted on is resolved in this order:

Your tenant’s branded short-link domain, if you’ve set one under Settings → General → Branded short-link domain. It must be a bare https:// host with no path, query, or fragment (for example https://go.yourbrand.com) whose DNS is CNAME’d to Orbit’s redirector. A malformed value falls back to the platform default rather than blocking the send.
The platform default host — https://api.orbit.devotel.io — used for every tenant that hasn’t configured a branded domain.

So a link minted for a tenant with no branded domain looks like https://api.orbit.devotel.io/l/abc123, while a tenant on go.yourbrand.com gets https://go.yourbrand.com/l/abc123. Both terminate TLS and serve the same redirect.

The platform default is api.orbit.devotel.io. Set a per-tenant branded domain if you want short, recognisable links your recipients trust.

Operator configuration

Self-hosting operators choose the platform default short-link host through environment variables. Per-tenant branded domains always take precedence over both.

Variable	Default	Description
`DEVOTEL_SHORT_LINK_DOMAIN`	(unset)	Dedicated branded short-link host (e.g. `https://orbt.to`). When set, platform-default short links are minted on it instead of the API origin.
`DEVOTEL_API_URL`	`https://api.orbit.devotel.io`	Fallback short-link host used when `DEVOTEL_SHORT_LINK_DOMAIN` is unset. This is also the public API origin, so it is not exclusive to short links.

Provision DNS, TLS, and a GET /l/:code ingress rule for the host before setting DEVOTEL_SHORT_LINK_DOMAIN. Point it at a host that does not yet serve the redirect and newly minted links will fail to resolve.

Example — shorten a URL

curl -X POST https://api.orbit.devotel.io/api/v1/links/ \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/promo?utm_campaign=may26",
    "campaign_id": "cmp_may26"
  }'

{
  "id": "link_abc123",
  "code": "q8kz2m",
  "original_url": "https://example.com/promo?utm_campaign=may26",
  "campaign_id": "cmp_may26",
  "message_id": null,
  "clicks": 0,
  "created_at": "2026-09-01T00:00:00Z",
  "short_url": "https://api.orbit.devotel.io/l/q8kz2m"
}

The response carries the minted link record plus the resolved short_url — on your branded host when one is configured, otherwise on the platform default. Embed short_url directly in outbound messages.

Insights

GET /api/v1/links/insights returns tenant-wide URL-shortener analytics in a single call: summary KPIs, the top links ranked by clicks, and a per-day click timeline. All parameters are optional.

Parameter	Type	Default	Description
`window_days`	integer (1–90)	`7`	Trailing window in days to aggregate clicks over.
`top_limit`	integer (1–50)	`10`	Number of top links to return, ranked by clicks.
`campaign_id`	string	—	Restrict insights to links attributed to this campaign.

curl "https://api.orbit.devotel.io/api/v1/links/insights?window_days=30&top_limit=5" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "summary": {
    "total_links": 1284,
    "total_clicks_window": 94730,
    "unique_visitors_window": 51206,
    "avg_clicks_per_link": 73.78,
    "verified_clicks_window": 88211,
    "verified_unique_visitors_window": 47904
  },
  "top_links": [
    {
      "link_id": "link_abc123",
      "code": "q8kz2m",
      "original_url": "https://example.com/promo?utm_campaign=may26",
      "campaign_id": "cmp_may26",
      "total_clicks": 1204,
      "unique_visitors": 986,
      "verified_clicks": 1189,
      "short_url": "https://api.orbit.devotel.io/l/q8kz2m"
    }
  ],
  "timeline": [
    { "date": "2026-08-03", "clicks": 2914 },
    { "date": "2026-08-04", "clicks": 3102 }
  ]
}

verified_* counts pass a bot/preview filter, so the verified count is a strict human-only subset of the raw count (never larger). An empty tenant returns zeroed KPIs, an empty top_links array, and an empty timeline. In the dashboard: the same aggregates power the cross-channel Insights → Link tracking page, and the SMS workspace surfaces a Link click-throughs panel (clicks, verified human clicks, tracked links, average per link over the last 7 days) alongside its delivery and cost metrics — so the messages where shortening is enabled have their click figures on the channel view itself.

Per-campaign link analytics

GET /api/v1/links/campaigns/{campaignId}/link-analytics rolls every tracked link minted for one SMS campaign into a single rollup: totals (minted links, raw clicks, verified human-only clicks, unique clicker recipients, attributed recipients, and the derived attribution rates), a per-channel breakdown, and a top-links ranking where each row carries its resolved short URL. A campaign with no shortened links reports zeroed totals — never a misleading or NaN rate.

Parameter	Type	Default	Description
`campaignId`	string (path)	—	Campaign identifier the links were minted for.
`window_days`	integer (1–365)	`7`	Trailing aggregation window in days.
`top_limit`	integer (1–50)	`10`	Maximum rows in the top-links ranking.

curl "https://api.orbit.devotel.io/api/v1/links/campaigns/cmp_may26/link-analytics?window_days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "campaign_id": "cmp_may26",
  "window_days": 30,
  "totals": {
    "links": 3,
    "clicks": 2411,
    "verified_clicks": 2360,
    "unique_clicker_recipients": 1804,
    "attributed_recipients": 9210,
    "unique_attribution_rate": 0.1958,
    "verified_attribution_rate": 0.9788
  },
  "by_channel": [
    {
      "channel": "sms",
      "links": 3,
      "clicks": 2411,
      "verified_clicks": 2360,
      "unique_clicker_recipients": 1804
    }
  ],
  "top_links": [
    {
      "link_id": "link_abc123",
      "code": "q8kz2m",
      "original_url": "https://example.com/promo?utm_campaign=may26",
      "channel": "sms",
      "clicks": 1204,
      "verified_clicks": 1189,
      "unique_recipients": 986,
      "short_url": "https://api.orbit.devotel.io/l/q8kz2m"
    }
  ]
}

The dashboard’s campaign detail screen consumes these same totals and ranking rows, so API consumers and the UI stay on one aggregate. A campaign with no shortened links returns zeroed totals, an empty by_channel array, and an empty top_links array; both attribution rates report 0 (never a NaN or misallocated rate):

{
  "campaign_id": "cmp_empty",
  "window_days": 30,
  "totals": {
    "links": 0,
    "clicks": 0,
    "verified_clicks": 0,
    "unique_clicker_recipients": 0,
    "attributed_recipients": 0,
    "unique_attribution_rate": 0,
    "verified_attribution_rate": 0
  },
  "by_channel": [],
  "top_links": []
}

Out-of-range values on window_days or top_limit are clamped to the bounds above rather than rejected.

Per-contact clicks

GET /api/v1/links/contacts/{contactId}/clicks resolves tracked short-link clicks back to a single recipient contact and returns the click history newest-first — useful for surfacing per-contact engagement in the CDP.

Parameter	Type	Default	Description
`contactId`	string (path)	—	Identifier of the contact whose clicks to return.
`limit`	integer (1–500)	`100`	Maximum number of clicks to return.

curl "https://api.orbit.devotel.io/api/v1/links/contacts/con_abc123/clicks?limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "contact_id": "con_abc123",
  "clicks": [
    {
      "click_id": "clk_9f02",
      "link_id": "link_abc123",
      "code": "q8kz2m",
      "original_url": "https://example.com/promo?utm_campaign=may26",
      "campaign_id": "cmp_may26",
      "message_id": "msg_77ab",
      "referrer": null,
      "country": "US",
      "clicked_at": "2026-08-31T19:41:22Z"
    }
  ],
  "total": 1
}

Each entry carries the resolved link (code, original_url, campaign_id, message_id) plus the click’s country and clicked_at. IP and user-agent are intentionally omitted here — the per-link stats endpoint is the device-forensics view; this history is the per-contact engagement view the Contacts detail page consumes for the CDP engagement panel.

Turn clickers into a retargetable segment

The same click attribution powers a one-shot audience builder: POST /api/v1/segments/from-clicks resolves the distinct recipient contacts who clicked a tracked short link (or any link in a campaign) and materialises them as a static, retargetable segment — with an optional recency window. See Segments for the request shape.

Landing Pages

No-code landing pages (microsites) are built from a block list and served under the same /links base path. A published page mints a trackable short URL and rolls up per-page visits and conversions by campaign and by originating message.

Method	Path	Purpose
`POST`	`/api/v1/links/landing-pages`	Create a draft landing page
`GET`	`/api/v1/links/landing-pages`	List landing pages (cursor-paginated; optional `status` filter)
`GET`	`/api/v1/links/landing-pages/{id}`	Fetch a single landing page
`PATCH`	`/api/v1/links/landing-pages/{id}`	Update title, content, campaign, or archive
`POST`	`/api/v1/links/landing-pages/{id}/publish`	Publish and mint the trackable short URL
`GET`	`/api/v1/links/landing-pages/{id}/analytics`	Per-page visits + conversions by campaign/message
`DELETE`	`/api/v1/links/landing-pages/{id}`	Delete a landing page (visit/conversion events cascade)

Create a draft, then publish it to mint the trackable short URL:

# 1. Create a draft
curl -X POST https://api.orbit.devotel.io/api/v1/links/landing-pages \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Spring launch", "campaign_id": "cmp_may26" }'

The draft response carries the page record with no short_url yet — it stays null until the page is published:

{
  "id": "lp_abc123",
  "slug": "spring-launch",
  "title": "Spring launch",
  "content": { "blocks": [] },
  "status": "draft",
  "short_link_id": null,
  "short_code": null,
  "campaign_id": "cmp_may26",
  "visits": 0,
  "conversions": 0,
  "published_at": null,
  "created_at": "2026-09-01T00:00:00Z",
  "updated_at": "2026-09-01T00:00:00Z",
  "short_url": null,
  "render_url": null
}

# 2. Publish it — the response carries the minted trackable short_url
curl -X POST https://api.orbit.devotel.io/api/v1/links/landing-pages/lp_abc123/publish \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "id": "lp_abc123",
  "slug": "spring-launch-7c1b",
  "title": "Spring launch",
  "content": { "blocks": [ { "type": "heading", "text": "Spring launch" } ] },
  "status": "published",
  "short_link_id": "link_def456",
  "short_code": "q8kz2m",
  "campaign_id": "cmp_may26",
  "visits": 0,
  "conversions": 0,
  "published_at": "2026-09-01T00:00:00Z",
  "created_at": "2026-09-01T00:00:00Z",
  "updated_at": "2026-09-01T00:00:00Z",
  "short_url": "https://api.orbit.devotel.io/l/q8kz2m",
  "render_url": "https://api.orbit.devotel.io/lp/q8kz2m"
}

In the dashboard: the landing-pages workspace renders this record and rolls visits/conversions into the per-page analytics payload below, so the page detail view and the API stay on one aggregate. The list endpoint accepts an optional status filter (draft, published, archived) alongside the standard cursor / limit pagination params. The analytics endpoint /api/v1/links/landing-pages/{id}/analytics accepts top_limit (1–50, default 10) to bound the per-campaign and per-message breakdowns:

{
  "page": {
    "id": "lp_abc123",
    "slug": "spring-launch-7c1b",
    "title": "Spring launch",
    "status": "published",
    "short_code": "q8kz2m",
    "visits": 1836,
    "conversions": 92,
    "short_url": "https://api.orbit.devotel.io/l/q8kz2m",
    "render_url": "https://api.orbit.devotel.io/lp/q8kz2m"
  },
  "analytics": {
    "totals": { "visits": 1836, "conversions": 92 },
    "by_campaign": [
      {
        "campaign_id": "cmp_may26",
        "campaign_name": "May 26 Promo",
        "visits": 1440,
        "conversions": 86
      }
    ],
    "by_message": [
      { "message_id": "msg_77ab", "visits": 1440, "conversions": 86 }
    ],
    "recent_conversions": [
      {
        "id": "evt_4092",
        "conversion_kind": "form_submit",
        "campaign_id": "cmp_may26",
        "message_id": "msg_77ab",
        "contact_id": "con_abc123",
        "value": null,
        "created_at": "2026-08-31T19:41:22Z"
      }
    ]
  }
}

In the dashboard: the landing-pages workspace’s per-page detail consumes this rollup. A page with no events returns zeroed totals with all three breakdown arrays empty.

API Reference

All Endpoints

Short Links API: branded links and click statistics

Short Links API

Using the SDKs

Default short-link host & branded domains

Operator configuration

Example — shorten a URL

Insights

Per-campaign link analytics

Per-contact clicks

Turn clickers into a retargetable segment

Landing Pages

See also

​Short Links API

​Using the SDKs

​Default short-link host & branded domains

​Operator configuration

​Example — shorten a URL

​Insights

​Per-campaign link analytics

​Per-contact clicks

​Turn clickers into a retargetable segment

​Landing Pages

​See also

Short Links API

Using the SDKs

Default short-link host & branded domains

Operator configuration

Example — shorten a URL

Insights

Per-campaign link analytics

Per-contact clicks

Turn clickers into a retargetable segment

Landing Pages

See also