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.

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/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

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"
  }'

The response includes the full short URL — embed it 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"

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"

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" }'

# 2. Publish it — the response carries the 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"

The list endpoint accepts an optional status filter (draft, published, archived) alongside the standard cursor / limit pagination params. The analytics endpoint accepts top_limit (1–50, default 10) to bound the per-campaign and per-message breakdowns.

API Reference

All Endpoints

Short Links API

Short Links API

Default short-link host & branded domains

Operator configuration

Example — shorten a URL

Insights

Per-contact clicks

Landing Pages

See also

​Short Links API

​Default short-link host & branded domains

​Operator configuration

​Example — shorten a URL

​Insights

​Per-contact clicks

​Landing Pages

​See also

Short Links API

Default short-link host & branded domains

Operator configuration

Example — shorten a URL

Insights

Per-contact clicks

Landing Pages

See also