Build on TRIMS with three endpoints and a bearer token.

TRIMS shortens links on your own domain and keeps the analytics behind them: per-click geography and device data, funnels and cohorts, conversion attribution back to the link that earned a sale, dynamic QR codes, and white-label workspaces for clients.

This documentation covers both the product (using the dashboard) and the platform (the REST API, webhooks, and integrations). Every concept links to a hands-on example.

What you can do with TRIMS

• Create branded short links on your own custom domains with memorable aliases.
• Track every click in realtime — geography, device, browser, referrer, and UTM parameters.
• Attribute leads and revenue back to the exact link and fire server-side ad pixels.
• Run A/B tests, geo & device routing, and round-robin rotation on any link.
• Generate styled, dynamic QR codes whose destination you can change any time.
• Invite your team, organize work into workspaces, and ship white-label client dashboards.
• Automate everything through a documented REST API, webhooks, and native integrations.

Get from zero to a tracked short link in four steps.

1. Create your account

Sign up with email or Google. Every new account starts on the generous Free plan — unlimited links, unlimited tracked clicks, and 30 days of analytics history. No credit card required.

2. Shorten your first link

From the dashboard, click New link, paste a destination URL, and (optionally) set a custom alias. Hit create — your link is live instantly on the global edge.

curl -X POST https://api.trims.app/api/links \
  -H "Authorization: Bearer $TRIMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://northlight.co/products/launch-2026",
    "customCode": "q4-launch",
    "workspaceId": "'$TRIMS_WORKSPACE'"
  }'

3. Share it & watch clicks arrive

Every visit is captured within milliseconds and streamed to your dashboard. Open the link's analytics to see geography, devices, and referrers update live.

4. Add your domain (optional)

Bring your own domain (e.g. go.northlight.co) so links are fully branded. See custom domains for the DNS setup.

A handful of objects power everything in TRIMS. Understanding how they relate makes the rest of the docs intuitive.

Custom domains

To brand links on your own domain, add it in Settings → Domains, then create a CNAME record pointing to our edge. SSL is provisioned automatically.

Type   Name              Value
CNAME  go.northlight.co       edge.trims.app.

The dashboard is your command center. The left sidebar switches between areas; the workspace switcher at the top lets you jump between brands and clients.

• Links — create, search, filter, and bulk-manage every short link.
• Analytics — realtime stream, breakdowns, funnels, cohorts, and ML insights.
• QR codes — design and export styled dynamic QR codes.
• Conversions — customers, leads, sales, and attributed revenue.
• Team — invite members, assign roles, and review the activity log.
• Settings — domains, API tokens, webhooks, billing, and security.

A link needs only a destination URL — everything else is optional. Create one from the dashboard's New link sheet or via the API.

const res = await fetch("https://api.trims.app/api/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIMS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://northlight.co/pricing",
    customCode: "pricing",
    workspaceId: process.env.TRIMS_WORKSPACE,
    tags: ["campaign", "q4"],
    title: "Q4 Pricing Page",
  }),
});
const link = await res.json();
console.log(link.shortUrl); // → https://go.northlight.co/pricing

Custom aliases

Aliases make links memorable and on-brand (go.northlight.co/webinar instead of a random code). Aliases are unique per domain. Custom aliases are included on every plan, including Free.

UTM builder

Attach UTM parameters so downstream analytics tools (GA4, your CDP) attribute traffic correctly. TRIMS appends them to the destination and also stores them as structured fields for its own reporting.

{
  "url": "https://northlight.co/blog/state-of-links",
  "customCode": "newsletter",
  "utmSource": "newsletter",
  "utmMedium": "email",
  "utmCampaign": "march-2026"
}

Social previews (OG metadata)

Override the title, description, and image that appear when a link is shared on social platforms. Great for making every shared link look intentional.

Expiration & password

• Set expiresAt to automatically disable a link at a chosen time, with an optional fallback URL.
• Set a password to gate the destination behind a prompt — ideal for private or paid content.
• Enable link cloaking to keep your branded URL visible in the address bar after redirect.

Route the same short link to different destinations based on where and how a visitor opens it. (Pro plan and above.)

Geo targeting

Send visitors from specific countries to localized pages. Anyone not matched falls through to the default URL.

{
  "url": "https://northlight.co/us",
  "geoRules": [
    { "countryCode": "GB", "destinationUrl": "https://northlight.co/uk" },
    { "countryCode": "DE", "destinationUrl": "https://northlight.co/de" }
  ]
}

Device & OS targeting

Point mobile users to an app store and desktop users to the web app, or split by OS (iOS, Android, Windows, macOS, Linux). Perfect for deep links.

Split traffic across multiple destinations to test which converts best, or distribute load evenly. (Pro plan and above.)

A/B testing

Assign weights (that sum to 100) across variants. TRIMS deterministically bucket-assigns visitors and reports conversion by variant.

curl -X POST https://api.trims.app/api/v1/links/{id}/ab-variants \
  -H "Authorization: Bearer $TRIMS_TOKEN" \
  -d '{
    "enabled": true,
    "variants": [
      { "destination_url": "https://northlight.co/a", "weight": 50 },
      { "destination_url": "https://northlight.co/b", "weight": 50 }
    ]
  }'

Round-robin rotation

Rotation cycles visitors evenly across a list of URLs — useful for affiliate pools or load spreading.

Create many links at once — via the API array endpoint or by uploading a CSV (both Pro and above).

[
  { "url": "https://northlight.co/a", "key": "promo-a" },
  { "url": "https://northlight.co/b", "key": "promo-b" },
  { "url": "https://northlight.co/c", "key": "promo-c" }
]

CSV import accepts a url column plus optional title, key, and tags columns. Shared options (folder, tags, UTMs) can be applied to the whole batch.

url,title,key
https://northlight.co/1,Landing One,promo-1
https://northlight.co/2,Landing Two,promo-2

Every link can generate a dynamic QR code. Because the code encodes the short link (not the destination), you can change where it points after it's printed.

• Style the code with brand colors, rounded modules, and a center logo.
• Track scans as clicks — QR scans flow into the same analytics as web clicks.
• Export as PNG, SVG, or PDF, or bulk-export a whole campaign as a ZIP.

curl https://api.trims.app/api/v1/links/{id}/qr?format=png \
  -H "Authorization: Bearer $TRIMS_TOKEN" --output qr.png

Every click is captured, enriched, and stored. Open any link to see its analytics, or view the workspace-wide dashboard for the full picture. Basic analytics are available on all plans; deeper reports require Pro.

What we capture per click

Reading a link's summary

{
  "total_clicks": 12483,
  "unique_visitors": 8121,
  "top_country": "US",
  "top_referrer": "linkedin.com",
  "period": "30d"
}

Supported period values include 24h, 7d, 30d, 90d, and all. Analytics history retention depends on your plan (up to unlimited on Premium).

The realtime feed shows clicks the instant they happen — city, link, and device — streamed over a live connection. It's the same pipeline that powers spike alerts.

• Live click ticker with geography and referrer.
• Active-visitor count updated every few seconds.
• Automatic spike detection with optional notifications.

Advanced analytics turn raw clicks into decisions. (Pro plan and above.)

Funnels

Define an ordered sequence of steps (e.g. click → lead → sale) and see conversion and drop-off at each stage.

Cohorts & retention

Group visitors by the week they first clicked and watch how many return over time — the classic retention curve, applied to link engagement.

Breakdowns

Slice any metric by country, device, browser, referrer, or UTM. Compare campaigns side by side.

TRIMS runs machine-learning models over your click data to surface what a human analyst would — automatically. (Pro plan and above.)

curl "https://api.trims.app/api/v1/analytics/ml/{code}?workspace={id}" \
  -H "Authorization: Bearer $TRIMS_TOKEN"

Close the loop between a click and a dollar. Send TRIMS a lead or sale event and it's attributed to the link (and customer) that drove it.

curl -X POST https://api.trims.app/api/v1/track/sale \
  -H "Authorization: Bearer $TRIMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_8f2a",
    "amount": 4900,
    "currency": "usd",
    "event_name": "Pro subscription"
  }'

Register the pixels you run on your own site so TRIMS can report what it observes for each one — events, unique actors and revenue, grouped by the event name the pixel tracks. (Pro plan and above.)

Add a pixel under Pixels with its platform, ID and the event name it tracks. TRIMS then matches your recorded leads and sales against that event name and reports them per pixel.

What this does not do yet: TRIMS does not send these events to Meta, Google, TikTok or LinkedIn. Those platforms are told about a conversion by the pixel or Conversions API integration on your own site, not by TRIMS. Server-side forwarding is on the roadmap; until it ships, the numbers here describe what TRIMS observed, not what any platform received.

A customer is a tracked identity that ties multiple events together. When you identify a visitor (by email or your own ID) TRIMS stitches their clicks and conversions into a single profile with lifetime value.

{
  "id": "cus_8f2a",
  "email": "nadia@company.com",
  "first_link": "q4-launch",
  "leads": 3,
  "sales": 2,
  "revenue": 124000,
  "created_at": "2026-02-14T09:31:00Z"
}

Workspaces isolate everything — links, domains, analytics, members, and billing — for a brand or client. Agencies typically run one workspace per client; product teams run one per brand.

• Switch instantly with the workspace switcher (top-left).
• Each workspace has its own custom domains and API tokens.
• Plan limits (domains, members) apply per workspace.

Invite teammates and assign a role. Role-based access control is available on Pro and above.

On Premium, make TRIMS disappear behind your brand. White-label workspaces get a custom dashboard domain, your logo and colors, and branded PDF/CSV reports your clients can read as a first-class asset.

• Custom dashboard domain (e.g. analytics.northlight.co).
• Logo, accent color, and favicon replacement.
• Branded, shareable public dashboards and exports.

The TRIMS REST API uses bearer API keys. Create one in Settings → API (API access requires the Pro plan), choose the scopes it should carry, and copy the key — it starts with trims_ and is shown only once. Send it in the Authorization header on every request.

curl https://api.trims.app/api/links?workspace=$TRIMS_WORKSPACE \
  -H "Authorization: Bearer $TRIMS_API_KEY"

Scopes & permissions

Every key carries one or more scopes. Scopes are enforced on each request: a key that lacks the required scope gets a 403 insufficient_scope, even if the key is otherwise valid. Grant a key the least privilege it needs.

{
  "code": 403,
  "error": "insufficient_scope",
  "message": "this API key does not have permission for this operation"
}

Full CRUD over links. Every endpoint is scoped to the key's workspace. Reads need links.read; writes need links.write.

List with filters

Filtering, sorting, and pagination are applied server-side across the whole workspace (not just the current page).

curl "https://api.trims.app/api/links?workspace=$TRIMS_WORKSPACE&tags=campaign&search=q4&status=active&sort=clicks&order=desc&limit=50&offset=0" \
  -H "Authorization: Bearer $TRIMS_API_KEY"

Update a link

import requests

requests.patch(
    "https://api.trims.app/api/links/{id}",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"title": "Updated title", "tags": ["q4", "paid"]},
)

Pull the same data that powers the dashboard. Requires analytics.read. Advanced breakdowns (funnels, cohorts, ML) require the Pro plan.

curl "https://api.trims.app/api/analytics/q4-launch?period=30d" \
  -H "Authorization: Bearer $TRIMS_API_KEY"

Subscribe to events and TRIMS will POST a signed JSON payload to your endpoint whenever they occur. Manage webhooks in Settings → Webhooks or via the API. Webhooks require API access (Pro).

Available events

• link.created, link.updated, link.deleted
• link.clicked — fired on every redirect (high volume).
• lead.created, sale.created — conversion events.
• spike.detected — anomalous traffic alert.

{
  "event": "sale.created",
  "created_at": "2026-03-02T12:04:11Z",
  "data": {
    "customer_id": "cus_8f2a",
    "link": "q4-launch",
    "amount": 4900,
    "currency": "usd"
  }
}

Verifying signatures

Each delivery includes an X-Trims-Signature header — an HMAC-SHA256 of the raw body using your webhook secret. Recompute and compare to reject spoofed requests.

import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

Building an app that acts on behalf of other TRIMS users? Use the OAuth 2.0 authorization-code flow instead of static tokens.

1. 1Redirect the user to /oauth/authorize with your client_id, redirect_uri, and requested scopes.
2. 2The user approves; TRIMS redirects back with a short-lived authorization code.
3. 3Exchange the code at /oauth/token for an access token (and refresh token).
4. 4Call the API with the access token; refresh it when it expires.

Rate limits

Two limits apply together, and both are counted per workspace across all of its tokens: a per-minute rate that bounds bursts, and a monthly request quota that is the actual ceiling for the billing period. Minting extra tokens does not raise either one.

Every response carries your current position, so you never have to guess:X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset describe the per-minute window, and X-RateLimit-Quota-Limit, X-RateLimit-Quota-Remaining and X-RateLimit-Quota-Reset describe the month. Once you pass 80% of the monthly quota, X-RateLimit-Quota-Warning appears — watch for it and slow down rather than waiting to be cut off.

Exceeding either limit returns 429, but they are not the same condition and should not be handled the same way. A burst rejection carries code: "rate_limit_exceeded" and a small Retry-After, so backing off works. An exhausted monthly quota carries code: "quota_exceeded" and a resetsAt timestamp that may be days away — retrying will not help, and the plan needs raising. Requests refused by either limit do not consume monthly quota.

Link-creation ceilings

Separately from the API limits above, link creation is capped per hour and per day. These are anti-abuse ceilings, not quotas on how many links you may own: the total number of links stays unlimited on every plan, and redirects are never metered, throttled, or stopped — a link that exists always resolves.

Exceeding one returns 429 with code: "link_quota_exceeded", the window that tripped (window: "hour" or "day"), limit, used, remaining, a resetAt timestamp and a Retry-After header — so a client can say exactly when creation resumes instead of guessing. Read the current position at any time from GET /api/shorten/quota.

Error format

Errors return the appropriate HTTP status and a JSON body. Plan-gated features return 403 with a machine-readable code.

{
  "error": "Advanced analytics require the Pro plan.",
  "code": "upgrade_required",
  "feature": "advanced_analytics",
  "requiredPlan": "pro"
}

Creating a link with nothing but fetch:

const res = await fetch("https://api.trims.app/api/v1/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIMS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://northlight.co/launch", key: "launch" }),
});
const link = await res.json();
console.log(link.shortUrl);

npx openapi-typescript https://api.trims.app/api/v1/openapi.json -o trims.d.ts

These are the integrations we plan to ship:

• Slack — get spike alerts and daily digests; shorten links with a slash command.
• Zapier / Make — trigger workflows on any TRIMS event, no code required.
• Shopify / Stripe — pipe orders in as sale conversions for true revenue attribution.
• Bitly import — migrate your existing links and history in one click.

Security is built in, not bolted on.

• 2FA (TOTP) — protect accounts with authenticator-app two-factor and recovery codes.
• Encryption — TLS 1.3 in transit, AES-256 at rest for sensitive fields.
• Automatic SSL — every custom domain gets a managed certificate.
• Bot & VPN detection — filter automated traffic so your metrics stay honest.
• Malware scanning — destinations are checked so your brand never fronts a bad link.
• Audit logs — every workspace records who changed what, and when.

Four tiers. Free includes unlimited links and unlimited tracked clicks with 30 days of history; paid plans add depth, longer retention, more domains and team features. Prices below are per month, billed annually.

See the full comparison on the pricing page. Upgrade or downgrade at any time. Your links keep redirecting on every plan, including after a downgrade.

We're here to help.

Pro plans include email support; Business adds priority support; Premium includes a dedicated success manager and SLA.