Logo of linkbreakers

Linkbreakers TypeScript SDK: Complete Integration Guide

Learn how to integrate the Linkbreakers TypeScript/JavaScript SDK in your Node.js and browser applications for programmatic link management, visitor tracking, and analytics. Includes installation, authentication, and real code examples.

Developer
2 min read
By Laurent Schaffner
Updated March 20, 2025

Short answer

The Linkbreakers TypeScript SDK enables programmatic link management, visitor identification, and analytics access from your TypeScript and JavaScript applications. Install it with npm install linkbreakers and authenticate using an API key from your dashboard to start creating and tracking links.

Installation

Install the SDK using your preferred package manager:

Bash 
# Using pnpm (recommended)
pnpm add linkbreakers

# Using npm
npm install linkbreakers

# Using yarn
yarn add linkbreakers

Creating an API key

Before using the SDK, create an API key:

  1. Log in to app.linkbreakers.com
  2. Navigate to Dashboard → API Tokens
  3. Click Create API Token
  4. Give your token a descriptive name
  5. Copy the generated key

Important: API keys provide full access to your workspace. Never commit them to version control or expose them in client-side code. Store them in environment variables or secret management systems.

Quick start

Initialize the SDK and create your first shortened link:

TypeScript 
import { Configuration, LinksApi } from 'linkbreakers';

// Configure API client
const config = new Configuration({
  accessToken: process.env.LINKBREAKERS_API_KEY,
  basePath: 'https://api.linkbreakers.com',
});

const linksApi = new LinksApi(config);

// Create a shortened link
const response = await linksApi.linksServiceCreate({
  createLinkRequest: {
    destination: 'https://example.com/product',
    name: 'Product Page - Spring Campaign',
    tags: ['marketing', 'spring-2025']
  }
});

console.log('Short URL:', response.link?.shortlink);
console.log('QR Code:', response.link?.qrcodeSignedUrl);

Authentication

The SDK uses Bearer token authentication. Always use the accessToken parameter in the configuration:

TypeScript 
// ✅ CORRECT - Sends "Authorization: Bearer {token}" header
const config = new Configuration({
  accessToken: 'your-api-key',
  basePath: 'https://api.linkbreakers.com',
});

// ❌ WRONG - Does not send authentication headers
const config = new Configuration({
  apiKey: 'your-api-key',  // This won't work!
});

Store your API key in environment variables:

TypeScript 
// .env file
LINKBREAKERS_API_KEY=your_api_key_here

Creating links with custom options

Customize your links with shortlinks, tags, metadata, and QR codes:

TypeScript 
import { Configuration, LinksApi } from 'linkbreakers';

const config = new Configuration({
  accessToken: process.env.LINKBREAKERS_API_KEY,
  basePath: 'https://api.linkbreakers.com',
});

const linksApi = new LinksApi(config);

// Create a link with a custom shortlink
const customLink = await linksApi.linksServiceCreate({
  createLinkRequest: {
    destination: 'https://example.com/docs',
    shortlink: 'docs',  // Creates lbr.ai/docs
    name: 'Documentation Home',
    fallbackDestination: 'https://example.com/404'
  }
});

// Use a custom domain (must be configured in dashboard)
const brandedLink = await linksApi.linksServiceCreate({
  createLinkRequest: {
    destination: 'https://example.com/signup',
    customDomainId: '123e4567-e89b-12d3-a456-426614174000',
    name: 'Signup Landing Page'
  }
});

// Create with metadata for tracking
const trackedLink = await linksApi.linksServiceCreate({
  createLinkRequest: {
    destination: 'https://example.com/offer',
    name: 'Summer Sale Campaign',
    metadata: {
      campaign_id: 'summer-sale-2025',
      utm_source: 'email',
      utm_medium: 'newsletter'
    }
  }
});

Managing links

List, retrieve, update, and delete links programmatically:

TypeScript 
import { Configuration, LinksApi } from 'linkbreakers';

const config = new Configuration({
  accessToken: process.env.LINKBREAKERS_API_KEY,
  basePath: 'https://api.linkbreakers.com',
});

const linksApi = new LinksApi(config);

// List all links with filtering
const listResponse = await linksApi.linksServiceList({
  pageSize: 50,
  tags: ['marketing'],
  search: 'campaign'
});

for (const link of listResponse.links || []) {
  console.log(`${link.name}: ${link.shortlink}`);
}

// Get a specific link by ID
const linkResponse = await linksApi.linksServiceGet({
  id: '123e4567-e89b-12d3-a456-426614174000',
  include: ['tags', 'qrcodeSignedUrl']
});

// Update a link
await linksApi.linksServiceUpdate({
  id: linkResponse.link?.id,
  updateLinkRequest: {
    name: 'Updated Campaign Name',
    tags: ['marketing', 'q2-2025']
  }
});

// Delete a link
await linksApi.linksServiceDelete({
  id: linkResponse.link?.id
});

Identifying visitors

Track and identify visitors using their LBID (Linkbreakers ID) from click/scan events:

TypeScript 
import { Configuration, VisitorsApi } from 'linkbreakers';

const config = new Configuration({
  accessToken: process.env.LINKBREAKERS_API_KEY,
  basePath: 'https://api.linkbreakers.com',
});

const visitorsApi = new VisitorsApi(config);

// Identify a visitor using their LBID (from URL parameter or tracking)
const response = await visitorsApi.visitorsServiceIdentify({
  identifyRequest: {
    lbid: 'visitor-lbid-from-url',  // Extract from ?lbid= parameter
    visitor: {
      data: {
        // System fields (prefixed with "$")
        '$email': 'user@example.com',
        '$phone': '+1234567890',
        '$firstName': 'John',
        '$lastName': 'Doe',

        // Custom attributes (no "$" prefix)
        'company': 'Acme Corp',
        'plan': 'premium',
        'signupDate': '2024-01-15'
      }
    },
    setOnce: false  // If true, only sets empty fields
  }
});

console.log('Created new profile:', response.created);
console.log('Visitor:', response.visitor);

Extracting LBID from URLs

When visitors click your links with conversion tracking enabled, the LBID appears as a query parameter:

TypeScript 
// In your application, extract LBID from the URL
const urlParams = new URLSearchParams(window.location.search);
const lbid = urlParams.get('lbid');

if (lbid) {
  // Use the SDK to identify the visitor
  const response = await visitorsApi.visitorsServiceIdentify({
    identifyRequest: {
      lbid: lbid,
      visitor: {
        data: {
          '$email': userEmail,
          // ... other visitor data
        }
      }
    }
  });
}

Working with QR codes

Generate links with QR codes:

TypeScript 
import { Configuration, LinksApi } from 'linkbreakers';

const config = new Configuration({
  accessToken: process.env.LINKBREAKERS_API_KEY,
  basePath: 'https://api.linkbreakers.com',
});

const linksApi = new LinksApi(config);

// Create a link with QR code generation
const response = await linksApi.linksServiceCreate({
  createLinkRequest: {
    destination: 'https://example.com/event',
    name: 'Event Registration',
    waitForQrcode: true,  // Wait for QR generation before returning
    tags: ['event', 'qr-code']
  }
});

console.log('QR Code URL:', response.link?.qrcodeSignedUrl);
console.log('QR Design ID:', response.link?.qrcodeDesignId);

Bulk operations

Create multiple links efficiently in a single API call:

TypeScript 
import { Configuration, LinksApi } from 'linkbreakers';

const config = new Configuration({
  accessToken: process.env.LINKBREAKERS_API_KEY,
  basePath: 'https://api.linkbreakers.com',
});

const linksApi = new LinksApi(config);

const response = await linksApi.linksServiceCreateBulk({
  createBulkLinksRequest: {
    links: [
      {
        destination: 'https://example.com/product-1',
        name: 'Product 1',
        tags: ['catalog'],
        metadata: { sku: 'PROD-001' }
      },
      {
        destination: 'https://example.com/product-2',
        name: 'Product 2',
        tags: ['catalog'],
        metadata: { sku: 'PROD-002' }
      }
    ]
  }
});

console.log(`Created ${response.links?.length} links`);

Accessing analytics

Retrieve visitor events and link performance data:

TypeScript 
import { Configuration, EventsApi, MetricsApi } from 'linkbreakers';

const config = new Configuration({
  accessToken: process.env.LINKBREAKERS_API_KEY,
  basePath: 'https://api.linkbreakers.com',
});

const eventsApi = new EventsApi(config);
const metricsApi = new MetricsApi(config);

// Get events for a specific link
const endDate = new Date();
const startDate = new Date();
startDate.setDate(startDate.getDate() - 30);

const eventsResponse = await eventsApi.eventsServiceList({
  linkId: '123e4567-e89b-12d3-a456-426614174000',
  startDate: startDate.toISOString(),
  endDate: endDate.toISOString(),
  pageSize: 100,
  include: ['visitor', 'device', 'link']
});

for (const event of eventsResponse.events || []) {
  console.log(`${event.action} - ${event.createdAt}`);
}

// Get workspace metrics
const metrics = await metricsApi.metricsServiceGetWorkspaceMetrics();
console.log('Total links:', metrics.totalLinks);
console.log('Total clicks:', metrics.totalClicks);

Framework integration

Node.js / Express:

TypeScript 
import express from 'express';
import { Configuration, LinksApi } from 'linkbreakers';

const app = express();
const config = new Configuration({
  accessToken: process.env.LINKBREAKERS_API_KEY,
  basePath: 'https://api.linkbreakers.com',
});

app.post('/api/create-link', async (req, res) => {
  const linksApi = new LinksApi(config);

  const response = await linksApi.linksServiceCreate({
    createLinkRequest: {
      destination: req.body.destination,
      name: req.body.name
    }
  });

  res.json({ shortlink: response.link?.shortlink });
});

Next.js API Routes:

TypeScript 
// app/api/create-link/route.ts
import { Configuration, LinksApi } from 'linkbreakers';
import { NextRequest, NextResponse } from 'next/server';

const config = new Configuration({
  accessToken: process.env.LINKBREAKERS_API_KEY,
  basePath: 'https://api.linkbreakers.com',
});

export async function POST(request: NextRequest) {
  const linksApi = new LinksApi(config);
  const body = await request.json();

  const response = await linksApi.linksServiceCreate({
    createLinkRequest: {
      destination: body.destination,
      name: body.name
    }
  });

  return NextResponse.json({ shortlink: response.link?.shortlink });
}

Frequently asked questions

Can I use this SDK in the browser?

Yes, the SDK works in browsers, but you should never expose your API key in client-side code. Use it only in server-side environments like Node.js, Next.js API routes, or serverless functions.

How do I handle rate limits?

The SDK will throw errors if you exceed rate limits. Implement retry logic with exponential backoff for production applications.

Does the SDK support TypeScript?

Yes, the SDK is written in TypeScript and includes full type definitions for autocompletion and type safety.

How do I get the LBID for visitor identification?

The LBID comes from the ?lbid= query parameter when visitors click your links with conversion tracking enabled. Extract it from the URL and pass it to the visitor identification API.

Can I create custom QR code designs?

Yes, use the QrcodeDesignsApi to create custom QR code designs with colors, shapes, and logos. Then reference the design ID when creating links.

Is async/await supported?

Yes, all SDK methods return Promises and work with async/await syntax.

Sources

Last reviewed

This article was last reviewed on March 20, 2025.

About the Author

LS

Laurent Schaffner

Founder & Engineer at Linkbreakers

Passionate about building tools that help businesses track and optimize their digital marketing efforts. Laurent founded Linkbreakers to make QR code analytics accessible and actionable for companies of all sizes.

Related Articles

How to use the Linkbreakers API

Complete guide to integrating with the Linkbreakers API - create QR codes, manage links, customize designs, track analytics, and automate workflows programmatically.

Analytics API

Access comprehensive QR code and visitor analytics through the Linkbreakers API. Learn how to retrieve campaign performance data, visitor insights, and engagement metrics programmatically for business intelligence integration.

How to integrate Linkbreakers with existing tech stack

Integrate Linkbreakers with your CRM, marketing automation, analytics platforms, and business systems through APIs, webhooks, and direct integrations. Learn best practices for seamless tech stack integration.

Back to Help Center