Skip to main content
The Dub TypeScript SDK provides a type-safe interface to interact with the Dub API from Node.js and TypeScript applications.

​
Installation

Install the SDK using your preferred package manager: 
npm install dub

​
Authentication

Initialize the SDK with your API key from the Dub Dashboard: 
import { Dub } from "dub";

const dub = new Dub({
  token: process.env.DUB_API_KEY,
});
Store your API key securely in environment variables. Never commit it to version control.

​
Quick Start

import { Dub } from "dub";

const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const link = await dub.links.create({
  url: "https://example.com/long-url",
  domain: "your-domain.com",
  key: "custom-key",
});

console.log(link.shortLink); // https://your-domain.com/custom-key
Retrieve links from your workspace with optional filtering: 
const links = await dub.links.list({
  search: "example",
  pageSize: 10,
});

links.result.forEach((link) => {
  console.log(`${link.shortLink} -> ${link.url}`);
  console.log(`Clicks: ${link.clicks}`);
  console.log(`Created: ${new Date(link.createdAt).toLocaleDateString()}`);
});

const updatedLink = await dub.links.update({
  linkId: "clx1...",
  url: "https://example.com/new-destination",
});

await dub.links.delete({
  linkId: "clx1...",
});

​
Domain Management

​
List Domains

const domains = await dub.domains.list();

domains.result.forEach((domain) => {
  console.log(domain.slug);
});

​
Get Domain Details

const domain = await dub.domains.get({
  slug: "your-domain.com",
});

​
Customer Tracking

​
List Customers

Retrieve customers using their external ID: 
const customers = await dub.customers.list({
  externalId: "user_123",
  includeExpandedFields: true,
});

const customer = customers.length > 0 ? customers[0] : null;

​
Conversion Tracking

​
Track Lead Conversions

await dub.track.lead({
  clickId: dubId,
  eventName: "Sign Up",
  customerExternalId: "user_123",
  customerName: "John Doe",
  customerEmail: "[email protected]",
  customerAvatar: "https://example.com/avatar.jpg",
});

​
Track Sale Conversions

await dub.track.sale({
  clickId: dubId,
  eventName: "Purchase",
  customerExternalId: "user_123",
  amount: 99.99,
  currency: "USD",
  metadata: {
    orderId: "order_456",
    productId: "prod_789",
  },
});

​
Error Handling

Wrap SDK calls in try-catch blocks to handle errors: 
try {
  const link = await dub.links.create({
    url: "https://example.com",
    domain: "your-domain.com",
  });
} catch (error) {
  console.error("Failed to create link:", error);
}

​
TypeScript Support

The SDK is written in TypeScript and provides full type definitions: 
import { Dub } from "dub";
import type { Link, Domain } from "dub";

const dub = new Dub({ token: process.env.DUB_API_KEY });

// TypeScript will infer the correct types
const link: Link = await dub.links.create({
  url: "https://example.com",
});

​
Next Steps

API Reference

Explore the complete API documentation

Client-Side Tracking

Add analytics tracking to your website

Build docs developers (and LLMs) love

Get started for freeTalk to us