Nimriz
SaaS & developers

Link shortener API: create links programmatically

Teams that ship campaigns at scale need links created by scripts, CRMs, or internal tools. Nimriz exposes a server-side REST API on api.nimriz.com so your automation code can create, update, and track branded short links without touching the dashboard.

  • Create, check, and update branded short links via HTTPS REST API on api.nimriz.com - retry-safe and idempotent
  • Bulk-create up to 25 links per request with per-row idempotency keys so imports never produce duplicates on retry
  • No-code path available: connect Zapier, Make, or n8n with scoped tokens for teams that want workflow automation without writing code
Start for freeAll use cases
API automation flow

A three-step pattern: preflight, create, store. Safe to retry at every step.

Server-side only
1
Check slug availability
POST /api/check-slug
{ "domain_id": "…", "slug": "spring-launch" }
→ { "available": true }
2
Create the link
POST /api/shorten
{ "domain_id": "…", "long_url": "https://…", "custom_slug": "spring-launch" }
→ { "url_id": "…", "short_url": "https://brand.to/spring-launch" }
3
Store the result
→ url_id (permanent) + short_url → persisted in your database or CRM

Creating, branding, and tracking short links by hand does not scale. When a campaign management system needs to generate thousands of unique branded URLs, a CRM needs to attach a short link to every new deal, or an e-commerce platform needs to bulk-produce product links from a catalog, a manual workflow becomes an immediate bottleneck. Mistakes compound: duplicate slugs, wrong destinations, missing expiry dates, and orphaned links all accumulate faster than a dashboard user can catch them.

Nimriz exposes a server-side REST API on api.nimriz.com so your backend can create, update, and read branded short links programmatically. Authentication uses a Workspace API Key passed as Authorization: Bearer <key> or X-Nim-Api-Key: <key>. The key is workspace-scoped and must live in a server-side environment variable only. It must never appear in browser code, mobile apps, or public repositories. All write operations, including link creation, slug updates, and password changes, must come from a trusted backend.

For teams that do not want to write code, Nimriz connects to Zapier, Make, and n8n through scoped installation tokens, available now. These no-code connectors let marketing operations, RevOps, and automation builders trigger link creation from any workflow tool without a backend deployment.

The result is branded links and per-link analytics generated reliably at whatever volume your system demands: single-link creation is idempotent by slug, bulk creation via POST /api/shorten/bulk supports up to 25 links per request with per-row idempotency keys, and lifecycle operations let you update destinations, slugs, and expiry dates without disrupting already-distributed URLs.

Who it is for

Platform and backend engineer

Needs a stable, documented REST API with predictable auth, idempotent bulk creation, and lifecycle management endpoints so link generation fits cleanly into existing CI/CD pipelines and backend services.

Growth and marketing-ops automator

Wants to wire Zapier, Make, or n8n to create campaign links automatically on deal creation, form submission, or campaign launch without deploying a backend service.

Agency and RevOps integrator

Manages multiple client domains from one workspace and needs domain-bound link creation, idempotent bulk imports from spreadsheets or CRM exports, and per-link analytics retrieval to include in client reports.

What you get

HTTPS automation endpoints

Create single links with POST /api/shorten, check slug availability with POST /api/check-slug, and update slugs, expiration dates, or passwords via dedicated PUT endpoints. All endpoints live on api.nimriz.com, authenticate with a workspace API key, and are built with retry-safe patterns so transient failures do not leave your automation code in an inconsistent state.

Policy-aware server side

Slug conventions, destination validation, redirect status code rules, and domain policies are all enforced centrally on the server, so your automation code stays lightweight and does not need to re-implement business rules locally. Forbidden schemes, loop prevention, and reserved-path protection are applied automatically before any link is created, keeping your workspace clean without per-request validation logic in your codebase.

Bulk link creation with idempotency

POST /api/shorten/bulk accepts up to 25 links per request, each with a per-row client_row_id and idempotency_key. Replaying the same idempotency_key returns the stored result instead of creating a duplicate, so network failures and retries during large imports are safe. Validation failures are returned per-row so a single bad row does not block the rest of the batch from completing successfully.

Full lifecycle management

After creation you can update a link's slug (PUT /api/update-slug), change or remove its expiration date (PUT /api/update-expiration), and set or clear a password gate (PUT /api/update-password) without taking the link offline. Always store the url_id returned at creation time as your stable reference: slugs can change, but the url_id is permanent for the lifetime of the link.

How it works

Build once, create links everywhere

A three-step automation pattern: preflight slug availability, create the link, store the result. Each step is safe to retry. All policy enforcement happens on the server so your client code stays thin.

1
Plan

Preflight slug availability (POST /api/check-slug) before creation - returns { available: true } or an error code so deterministic slug workflows never hit a surprise conflict.

2
Publish

Create the short link (POST /api/shorten) with optional custom_slug, expires_at, password, and redirect_status_code - policy validation runs server-side.

3
Measure

Store url_id as your durable reference - slugs can change via PUT /api/update-slug, but url_id is permanent for the life of the link.

    API & automation featuresTrust and privacyFAQ
    Example
    On deal created in CRM
    1. POST /api/check-slug - confirm slug is free
    2. POST /api/shorten with deal ID as custom_slug
    3. Store url_id and short_url on the contact record
    4. Include short_url in outbound email template
    Result
    https://brand.to/deal-4872 - personalized landing page

    Setup

    1. 1
      Generate a Workspace API Key
      Go to Dashboard - Settings - Integrations - API access and click Generate API key. Copy the key immediately and store it in a server-side environment variable. It is shown only once and must never appear in browser code, mobile apps, or public repositories.
    2. 2
      Create your first link from your backend

      Call POST /api/shorten from your server with the Authorization: Bearer header. A minimal request looks like this:

      curl example
      curl -X POST https://api.nimriz.com/api/shorten \
      -H "Authorization: Bearer $WORKSPACE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "domain_id": "YOUR_DOMAIN_UUID",
      "long_url": "https://example.com/landing?utm_source=email",
      "custom_slug": "spring-launch",
      "expires_at": "2026-12-31T23:59:59Z",
      "redirect_status_code": 302
      }'
      Response
      {
      "url_id": "22222222-2222-2222-2222-222222222222",
      "short_code": "spring-launch",
      "short_url": "https://links.example.com/spring-launch",
      "expires_at": "2026-12-31T23:59:59.000Z"
      }

      Store the returned url_id as your durable reference. Use short_url as the display and share value.

    3. 3
      Use bulk creation with idempotency keys for imports

      For catalog imports, batch campaigns, or any job-style link creation, use POST /api/shorten/bulk. Send up to 25 items per request. Each item carries a client_row_id (your stable row identifier) and an idempotency_key (a stable key for the exact intended outcome). Replaying the same key on retry returns the stored result instead of creating a duplicate.

      JS fetch example (server-side)
      const res = await fetch(
      'https://api.nimriz.com/api/shorten/bulk',
      { method: 'POST',
      headers: {
      'Authorization': `Bearer ${WORKSPACE_API_KEY}`,
      'Content-Type': 'application/json'
      },
      body: JSON.stringify({
      domain_id: DOMAIN_ID,
      items: rows.map(row => ({
      client_row_id: row.id,
      idempotency_key: `import-${sessionId}-${row.id}`,
      long_url: row.destinationUrl,
      custom_slug: row.slug
      }))
      })
      }
      );
      const { results } = await res.json();
      // Per-row: check result.ok, result.url_id, result.short_url
    4. 4
      Read analytics via the links API
      Retrieve per-day click totals for any link with GET /api/v1/links/:id/analytics. Pass range_days (1-365, default 30), include_bots (0 or 1), and touch_type (short_link_click or qr_scan) as query parameters. You can also list all links in the workspace with GET /api/v1/links or look up a specific link by short URL with GET /api/v1/links/find.
    5. 5
      Connect Zapier, Make, or n8n for a no-code path
      Teams that do not want to write backend code can connect Zapier, Make, or n8n using scoped installation tokens, available now from Dashboard - Settings - Integrations. These connectors let you trigger link creation from any supported trigger: a new CRM deal, a completed form submission, a spreadsheet row, or any other workflow event. Rotating a key in the Integrations settings does not require reconnecting the platform integration.

    What good looks like

    Update a link after creation

    All three lifecycle endpoints require only the url_id returned at creation time. The original short URL continues to work while the update is applied.

    Update slug
    PUT https://api.nimriz.com/api/update-slug
    { "url_id": "22222…", "new_slug": "spring-v2" }
    Extend expiration
    PUT https://api.nimriz.com/api/update-expiration
    { "url_id": "22222…", "expires_at": "2027-03-01T00:00:00Z" }
    Remove password protection
    PUT https://api.nimriz.com/api/update-password
    { "url_id": "22222…", "password": null }

    Frequently asked questions

    Where do I get an API key and is it safe to use client-side?
    Generate a Workspace API Key at Dashboard - Settings - Integrations - API access. The key is shown only once, so copy it immediately and store it in a server-side environment variable. It must never appear in browser code, mobile apps, or public repositories. All link management API calls must come from a trusted backend server. The key is workspace-scoped: it can only operate within the workspace it was generated in and cannot access other workspaces.
    Can I create multiple links in one API call?
    Yes. POST /api/shorten/bulk accepts up to 25 links per request. Each item in the batch requires a client_row_id (your stable identifier for matching results to inputs) and an idempotency_key (a stable key for the exact intended outcome). If you replay the same idempotency_key, the API returns the stored result with idempotent: true instead of creating a duplicate. Validation failures are returned per-row, so one bad row does not fail the entire batch.
    Do you have a no-code option for teams that do not want to write code?
    Yes. Nimriz connects to Zapier, Make, and n8n through scoped installation tokens, available now. These no-code integrations let marketing operations, RevOps, and automation builders create and manage links from within their existing workflow tools without deploying a backend service. See Integrations for the current list of supported connectors.
    How is the Conversion API different from the workspace API key?
    They are two separate credentials with two separate purposes. The Workspace API Key (used as Authorization: Bearer or X-Nim-Api-Key) is for link management: creating, reading, and updating short links. The Conversion API uses a separate signing secret, generated at Dashboard - Settings - Integrations under Conversion tracking. Conversion events are sent to POST /api/conversions/callback/:workspace_id and authenticated with an HMAC-SHA256 signature using the conversion secret, not the workspace API key. Keeping them separate lets you rotate credentials independently.
    What are the rate limits and what happens when I hit them?
    Monthly link-creation quotas and plan limits apply. If you exceed your monthly quota, the API returns HTTP 429 with error code monthly_quota_exceeded. If a request exceeds a plan capability, it returns HTTP 403 with plan_limit. Retry 429, 502, 503, and 504 responses with exponential backoff. Do not retry 4xx errors other than 429, as those indicate input or policy problems that will not resolve on retry. For high-volume imports, prefer POST /api/shorten/bulk over rapid individual POST /api/shorten requests to stay within your quota efficiently.
    Can I update a link's destination, slug, or expiry after it is created?
    Yes, through three dedicated endpoints. Use PUT /api/update-slug with the link's url_id and a new_slug to change the slug (note: the old slug stops working immediately). Use PUT /api/update-expiration with expires_at (an ISO 8601 timestamp) to set or extend the expiry, or pass null to remove it when the domain policy allows. Use PUT /api/update-password with a new password string or null to remove password protection. All three operations use the permanent url_id as the identifier, so store it at creation time.
    Can I automate QR code generation via the API?
    Yes, on Professional and Enterprise plans. POST /api/v1/qr/generate renders a QR asset (PNG or SVG) for an existing link identified by url_id. You can apply a QR preset or pass inline style overrides. Additional endpoints let you manage QR presets (GET, POST, PUT, DELETE /api/v1/qr/presets) and download the effective QR asset directly with GET /api/v1/links/:id/qr. All QR endpoints use the same workspace API key auth model.
    How do I look up a link or retrieve analytics via the API?
    Use GET /api/v1/links/:id to retrieve a single link by its url_id, GET /api/v1/links to list recent links in the workspace (up to 100 per request), or GET /api/v1/links/find to look up a link by its full short URL or by domain_id plus short_code. For click analytics, GET /api/v1/links/:id/analytics returns per-day totals with optional range_days, include_bots, and touch_type parameters. All retrieval endpoints authenticate with the same workspace API key.

    Related use cases

    Campaign links
    Build campaign links and track performance.
    Workflow automation
    Automate links across tools and CRMs.
    Conversion tracking
    Track outcomes on programmatically created links.
    Organize links with spaces and tags
    Organize links into spaces and tags as you create them.

    Deeper reading

    Full API referenceDeveloper hubAuth model and API key securityIntegration patterns and retry guidanceRate limits, quotas, and error codesAPI and automation feature overviewGlossary: API URL shortenerBlog: automating link management

    Ready to get started?

    Create your account and start with the Starter workflow. Compare plans when you need higher limits or supported-plan capabilities.

    Start for freeView pricing