Organizing links

Learn how to associate links with users, campaigns, teams, and other entities within your system.

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:

Method	Type	Description	Use case
External ID	One-to-one	A unique identifier for a link within your system.	Associating referral links with users in your system.
Tenant ID	One-to-many	The ID of the tenant that created the link.	Grouping all links created by a user/team in your system.
Tags	Many-to-many	Grouping links by tags	Organizing links by campaign / user / various for flexible, multi-dimensional filtering and reporting
Folders	One-to-many	The 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.

Create link with an externalId

Here is an example of how to create a link with an externalId:

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",
  externalId: "12345",
});

Retrieve link by externalId

Let’s see how to retrieve a link by its externalId:

Node.js

import { Dub } from "dub";

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

const link = await dub.links.get({
  externalId: "12345",
});

Update link by externalId

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.

Node.js

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.

Node.js

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.

Create link with tenantId

Let’s see how to create a link with a tenant ID:

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",
  tenantId: "12345",
});

Retrieve links by tenantId

Here is how to retrieve links by tenant ID:

Node.js

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.

Node.js

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:

• Organize your links by campaigns, clients, or any other categories you can think of.
• Filter your links by tags and get a shareable link to the filtered results.
• Filter your analytics by tags to see how your campaigns are performing.

Create link with tags

You can use either pass the tag ID or tag name to create a link with tags.

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://example.com",
  tagIds: ["clux0rgak00011..."],
});

Retrieve links by tags

You can retrieve links by tag by tags.

Node.js

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).

Node.js

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:

• Organize your links into directories
• Filter your links by folder and get a shareable link to the filtered results.
• Filter your analytics by folder to see how your campaigns are performing.

Create link with folderId

You can use the folder ID to create a link with a folder.

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://example.com",
  folderId: "clux0rgak00011...",
});

Retrieve links by folderId

Here is how to retrieve links by folder ID:

Node.js

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.

Node.js

import { Dub } from "dub";

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

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