Data model

A quick overview of how Dub is structured.

Whether you are using Dub’s API or not, this page is a quick way to understand how Dub works.

Within Dub, all data belongs to a Workspace. Within a workspace, you have Links, Domains, Tags, and more.

Workspace

Workspaces is the defacto way of organizing your links and working with your team on Dub. You can think of a Dub workspace like a workspace on Slack or Discord – it’s a shared space where you can invite your team members to collaborate on links.

When interacting with Dub’s API, you’ll also need to create a workspace API key to authenticate your requests.

Workspace model

id · string · required

The unique ID of the workspace.

name · string · required

The name of the workspace.

slug · string · required

The slug of the workspace.

logo · string | null · required

The logo of the workspace.

usage · number · required

The usage of the workspace.

usageLimit · number · required

The usage limit of the workspace.

linksUsage · number · required

The links usage of the workspace.

linksLimit · number · required

The links limit of the workspace.

domainsLimit · number · required

The domains limit of the workspace.

tagsLimit · number · required

The tags limit of the workspace.

usersLimit · number · required

The users limit of the workspace.

plan · string · required

The plan of the workspace.

stripeId · string | null · required

The Stripe ID of the workspace.

billingCycleStart · number · required

The date and time when the billing cycle starts for the workspace.

createdAt · string · required

The date and time when the workspace was created.

users · object[] · required

The role of the authenticated user in the workspace.

Show properties

users.role · string · required

The role of the authenticated user in the workspace.

domains · object[] · required

The domains of the workspace.

Show properties

domains.slug · string

The domain of the workspace.

domains.primary · string

Indicates if the domain is the primary domain.

Links

Links are the bread and butter of Dub. You can shorten any URL to a Dub link, which you can then share with your audience. Links can be created, updated, and deleted via the Dub API or the Dub dashboard.

Link model

id · string · required

The unique ID of the short link. Prefixed with link_.

domain · string · required

The domain of the short link. If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains).

key · string · required

The short link slug. If not provided, a random 7-character slug will be generated.

url · string · required

The destination URL of the short link.

shortLink · string · required

The full URL of the short link, including the https protocol (e.g. https://d.to/try).

trackConversion · boolean · default: "false"

Whether to track conversions for the short link.

externalId · string | null

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with ext_ when passed as a query parameter). This key is unique across your workspace.

tenantId · string | null

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.

archived · boolean · default: "false" · required

Whether the short link is archived.

expiresAt · string | null

The date and time when the short link will expire in ISO-8601 format.

expiredUrl · string | null

The URL to redirect to when the short link has expired.

password · string | null

The password required to access the destination URL of the short link.

proxy · boolean · default: "false" · required

Whether the short link uses Custom Social Media Cards feature.

title · string | null

The title of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

description · string | null

The description of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

image · string | null

The image of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

video · string | null

The custom link preview video (og:video). Will be used for Custom Social Media Cards if proxy is true. Learn more: https://d.to/og

rewrite · boolean · default: "false" · required

Whether the short link uses link cloaking.

doIndex · boolean · default: "false" · required

Whether to allow search engines to index the short link.

ios · string | null

The iOS destination URL for the short link for iOS device targeting.

android · string | null

The Android destination URL for the short link for Android device targeting.

publicStats · boolean · default: "false" · required

Whether the short link’s stats are publicly accessible.

tags · object[] | null

The tags assigned to the short link.

Show properties

tags.id · string

The unique ID of the tag.

tags.name · string

The name of the tag.

tags.color · string

The color of the tag.

webhookIds · string[]

The IDs of the webhooks that the short link is associated with.

comments · string | null

The comments for the short link.

qrCode · string

The full URL of the QR code for the short link (e.g. https://api.dub.co/qr?url=https://d.to/try).

utm_source · string | null

The UTM source of the short link.

utm_medium · string | null

The UTM medium of the short link.

utm_campaign · string | null

The UTM campaign of the short link.

utm_term · string | null

The UTM term of the short link.

utm_content · string | null

The UTM content of the short link.

userId · string

The user ID of the creator of the short link.

workspaceId · string

The workspace ID of the short link.

clicks · number · default: "0" · required

The number of clicks on the short link.

leads · number · default: "0" · required

The number of leads the short link has generated.

sales · number · default: "0" · required

The number of sales the short link has generated.

saleAmount · number · default: "0" · required

The total dollar amount of sales the short link has generated (in cents).

lastClicked · string | null

The date and time when the short link was last clicked.

createdAt · string

The date and time when the short link was created.

updatedAt · string

The date and time when the short link was last updated.

programId · string | null

The ID of the program the short link is associated with.

Domains

On Dub, you can add custom domains to create branded short links for better brand recognition. You can also set a primary domain for it to be used as the default domain for new links (both via the API and the dashboard).

Domain model

id · string · required

The unique identifier of the domain.

slug · string · required

The domain name.

verified · boolean · default: false · required

Whether the domain is verified.

primary · boolean · default: false · required

Whether the domain is the primary domain for the workspace.

archived · boolean · default: false · required

Whether the domain is archived.

placeholder · string · default: "https://dub.co/help/article/what-is-dub" · required

Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened.

expiredUrl · string | null · required

The URL to redirect to when a link under this domain has expired.

notFoundUrl · string | null · required

The URL to redirect to when a link under this domain doesn’t exist.

createdAt · string · required

The date the domain was created.

updatedAt · string · required

The date the domain was last updated.

registeredDomain · object | null · required

The registered domain record.

Show properties

id · string · required

The ID of the registered domain record.

createdAt · string · required

The date the domain was created.

expiresAt · string · required

The date the domain expires.

Tags

Tags are a way to organize your links. You can add tags to your links to categorize them and make them easier to find. You can also filter analytics by tags to get a better understanding of how your campaigns are performing.

Tag model

id · string · required

The unique ID of the tag.

name · string · required

The name of the tag.

color · string · required

The color of the tag.