When creating links programmatically with Dub, you might want a way to associate them with a user or other identifiers in your system. There are a few ways to do this, depending on your data structure:
MethodTypeDescriptionUse case
External IDOne-to-oneA unique identifier for a link within your system.Associating referral links with users in your system.
Tenant IDOne-to-manyThe ID of the tenant that created the link.Grouping all links created by a user/team in your system.
TagsMany-to-manyGrouping links by tagsOrganizing links by campaign / user / various for flexible, multi-dimensional filtering and reporting
FoldersOne-to-manyThe ID of the folder that contains the link.Organizing links into hierarchical folder structures for better organization.

​
External ID

In certain scenarios, it is essential to identify links within your system. For instance, you may need to associate a link with a user without storing the Dub link ID directly in your database (e.g. for referral links). The externalId field serves this purpose effectively. It acts as a unique identifier within your database, allowing you to associate it with a corresponding link in Dub’s system. Dub allows you to create links using an externalId and subsequently retrieve them by the same identifier.
externalId should be a unique value across your workspace. Trying to create a link with an externalId that already exists will result in a 409 conflict error error.
Here is an example of how to create a link with an externalId: 
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",
  externalId: "12345",
});
Let’s see how to retrieve a link by its externalId: 
import { Dub } from "dub";

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

const link = await dub.links.get({
  externalId: "12345",
});
In addition to updating a link by its linkId, you can also update a link by its externalId.
Make sure to prefix the externalId with ext_. For example, if your externalId is 12345, you should pass ext_12345.
import { Dub } from "dub";

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

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

​
Retrieve analytics by externalId

You can also retrieve analytics for a link by its externalId. This is helpful for fetching the analytics for a given link using the unique identifier from your system. 
import { Dub } from "dub";

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

const analytics = await dub.analytics.retrieve({
  externalId: "ext_12345",
});

​
Tenant ID

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. This is useful if you have a system that lets your users create their own links, and you want to group them on a tenant level. Let’s see how to create a link with a tenant ID: 
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",
  tenantId: "12345",
});
Here is how to retrieve links by tenant ID: 
import { Dub } from "dub";

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

const result = await dub.links.list({
  tenantId: "12345",
});

​
Retrieve analytics by tenantId

You can retrieve analytics by tenantId by passing the tenantId prop. This is helpful for fetching the analytics for all the links under a specific tenant, or the total analytics for a tenant. 
import { Dub } from "dub";

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

const analytics = await dub.analytics.retrieve({
  tenantId: "12345",
});

​
Tags

Tags are a great way to organize your links on Dub. With tags, you can: You can use either pass the tag ID or tag name to create a link with tags. 
import { Dub } from "dub";

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

const link = await dub.links.create({
  url: "https://example.com",
  tagIds: ["clux0rgak00011..."],
});
You can retrieve links by tag by tags. 
import { Dub } from "dub";

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

const result = await dub.links.list({
  tagNames: ["tag1"],
});

​
Retrieve analytics by tags

You can retrieve analytics for a tag (or multiple tags) by passing the tagIds prop. This is helpful for fetching the analytics for all the links under a specific tag, or the total analytics for a tag (or multiple tags). 
import { Dub } from "dub";

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

const analytics = await dub.analytics.retrieve({
  tagIds: ["tag_xxx"],
});

​
Folders

Folders are a hierarchical way to organize your links on Dub. With folders, you can: You can use the folder ID to create a link with a folder. 
import { Dub } from "dub";

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

const link = await dub.links.create({
  url: "https://example.com",
  folderId: "clux0rgak00011...",
});
Here is how to retrieve links by folder ID: 
import { Dub } from "dub";

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

const result = await dub.links.list({
  folderId: "clux0rgak00011...",
});

​
Retrieve analytics by folderId

You can retrieve analytics by folderId by passing the folderId prop. This is helpful for fetching the analytics for all the links under a specific folder, or the total analytics for a folder. 
import { Dub } from "dub";

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

const analytics = await dub.analytics.retrieve({
  folderId: "clux0rgak00011...",
});