Introduction

Learn how to use Dub to programmatically create, update, and delete links at scale.

Links are the bread and butter of Dub.

Everything on Dub starts with a link. Whether you’re creating:

• a handful of links for your marketing campaign
• hundreds of links for your affiliate program
• thousands of links, programmatically, for your SMS campaign

In this guide, we’ll cover the link model, how to create links, and more.

The link model

The link model consists of the following properties:

Property	Description	Example
id	The unique identifier of the link (prefixed with link_)	link_eBKA4MT44XnI17hYLchkjUOd
url	The destination URL of the link	https://dub.co/home
shortLink	The shortened version of the link (including https)	https://dub.link/claim
domain	The domain of the link	dub.link
key	The short link slug	claim

For more advanced features like custom link previews, conversion tracking, and more, see the full list of properties here.

You can use the various Dub SDKs to programmatically manage your links.

Create a link

The url field, representing the destination URL, is the sole mandatory parameter required for the creation of a new short link.

Node.js

import { Dub } from "dub";

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

const link = await dub.links.create({
  url: "https://google.com",
});

Check out the full API reference for the link creation endpoint.

Update a link

An existing link can be updated by providing the id to the update method. This method returns the updated link as a response.

You can use either the linkId or an externalId prefixed with ext_ which is a unique identifier for the link in your own database to associate it with the link in Dub’s system.

Node.js

import { Dub } from "dub";

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

const link = await dub.links.update("link_eBKA4MT44XnI17hYLchkjUOd", {
  url: "https://www.google.uk", // new URL
});

Check out the full API reference for the link update endpoint.

Upsert a link

Upserting a link is a combination of creating and updating a link. If a link with the same URL already exists, return it (or update it if there are any changes). Otherwise, a new link will be created.

This allows you to use the upsert method without the necessity of checking for the link’s existence beforehand.

Node.js

import { Dub } from "dub";

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

const link = await dub.links.upsert({
  url: "https://google.com", // will always be the same short link
});

Check out the full API reference for the link upsert endpoint.