kurl.win
DevelopersAPIIntegration

Integrating URL Shortening into Your SaaS Product

James Park •

Building a product that generates links? Whether it’s share buttons, referral systems, or reporting features, embedded URL shortening can elevate user experience. Here’s how to integrate it properly.

Why Embed URL Shortening?

Your product generates links:

  • Share links for content
  • Referral links for growth
  • Preview links for collaboration
  • Export links for reports

Long, ugly links hurt UX. Short links solve this.

Integration Approaches

Approach 1: API Integration

Direct API calls for maximum control:

async function shortenUrl(longUrl, customSlug) {
  const response = await fetch('https://api.kurl.win/shorten', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: longUrl,
      slug: customSlug
    })
  });
  return response.json();
}

Approach 2: SDK Integration

Pre-built libraries for faster development:

import { KurlClient } from '@kurl/sdk';

const kurl = new KurlClient(apiKey);
const shortLink = await kurl.shorten(longUrl);

Approach 3: Webhook Integration

Automatic shortening on events:

  • New content published → Shorten link
  • User signs up → Create referral link
  • Report generated → Create share link

Key Implementation Decisions

Synchronous vs Asynchronous

Synchronous: Block until link is ready

  • Simple implementation
  • Adds latency to user actions
  • Best for: Single link creation

Asynchronous: Create in background

  • Better UX for bulk operations
  • Requires status tracking
  • Best for: Batch processing, imports

Caching Strategy

Avoid unnecessary API calls:

  • Cache shortened links
  • Set appropriate TTLs
  • Invalidate on destination changes

Error Handling

Plan for failures:

  • API rate limits
  • Network timeouts
  • Invalid destinations
  • Graceful fallbacks to long URLs

Advanced Features

Custom Slugs

Let users personalize:

const link = await kurl.shorten(url, {
  slug: `${username}-invite`
});

Time-limited access:

const link = await kurl.shorten(url, {
  expiresAt: '2026-12-31T23:59:59Z'
});

Click Callbacks

Real-time notifications:

const link = await kurl.shorten(url, {
  webhookUrl: 'https://yourapp.com/webhooks/clicks'
});

White-Label Considerations

Custom Domains

Use your own domain:

  • share.yourproduct.com/xyz
  • Requires DNS configuration
  • Maintains brand consistency

Branded Appearance

When users see links:

  • Your domain, not third-party
  • Consistent with product experience
  • No confusion about trusted sources

Rate Limiting and Quotas

Planning Capacity

Estimate your volume:

  • Links created per day
  • Clicks expected per link
  • Peak usage periods

Implementing Limits

Protect against abuse:

  • Per-user rate limits
  • Daily quotas
  • Burst allowances

Security Best Practices

API Key Management

  • Never expose keys client-side
  • Rotate keys periodically
  • Use environment variables
  • Scope keys appropriately

Destination Validation

Before shortening:

  • Verify URL format
  • Check against blocklists
  • Validate user permissions

Audit Logging

Track all operations:

  • Who created the link
  • When it was created
  • What destination was used

Testing Your Integration

Unit Tests

Test API interactions:

  • Successful shortening
  • Error handling
  • Timeout behavior

Integration Tests

End-to-end validation:

  • Full user workflow
  • Cache behavior
  • Webhook delivery

Load Testing

Verify at scale:

  • Concurrent requests
  • Response times under load
  • Error rates at volume

Monitoring Production

Key Metrics

Track integration health:

  • API response times
  • Error rates
  • Cache hit rates
  • Webhook delivery success

Alerting

Set up notifications for:

  • API errors above threshold
  • Unusual usage patterns
  • Quota approaching limits

Great products deserve great links. Build the integration right.