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 idThe unique identifier of the link (prefixed with link_) link_eBKA4MT44XnI17hYLchkjUOdurlThe destination URL of the link https://dub.co/homeshortLinkThe shortened version of the link (including https) https://dub.link/claimdomainThe domain of the link dub.linkkeyThe short link slug claim
For more advanced features like custom link previews, conversion tracking, and more, see the full list of properties below;
Full list of link properties
The unique ID of the short link. Prefixed with link_.
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).
The short link slug. If not provided, a random 7-character slug will be
generated.
The destination URL of the short link.
The full URL of the short link, including the https protocol (e.g.
https://dub.sh/try).
[BETA] Whether to track conversions for the short link.
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.
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.
Whether the short link is archived.
The date and time when the short link will expire in ISO-8601 format.
The URL to redirect to when the short link has expired.
The password required to access the destination URL of the short link.
Whether the short link uses Custom Social Media Cards feature.
The title of the short link generated via api.dub.co/metatags. Will be used
for Custom Social Media Cards if proxy is true.
The description of the short link generated via api.dub.co/metatags. Will be
used for Custom Social Media Cards if proxy is true.
The image of the short link generated via api.dub.co/metatags. Will be used
for Custom Social Media Cards if proxy is true.
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
Whether the short link uses link cloaking.
Whether to allow search engines to index the short link.
The iOS destination URL for the short link for iOS device targeting.
The Android destination URL for the short link for Android device targeting.
Whether the short link’s stats are publicly accessible.
The unique ID of the tag assigned to the short link. This field is deprecated
– use tags instead.
The tags assigned to the short link.
The unique ID of the tag.
The IDs of the webhooks that the short link is associated with.
The comments for the short link.
The full URL of the QR code for the short link (e.g.
https://api.dub.co/qr?url=https://dub.sh/try).
The UTM source of the short link.
The UTM medium of the short link.
The UTM campaign of the short link.
The UTM term of the short link.
The UTM content of the short link.
The user ID of the creator of the short link.
The workspace ID of the short link.
The number of clicks on the short link.
[BETA]: The number of leads the short link has generated.
[BETA]: The number of sales the short link has generated.
[BETA]: The total dollar amount of sales the short link has generated (in
cents).
The date and time when the short link was last clicked.
The date and time when the short link was created.
The date and time when the short link was last updated.
The project ID of the short link. This field is deprecated – use workspaceId
instead.
The ID of the program the short link is associated with.
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.
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.
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.
