dub.links.upsert

Upsert a link for the authenticated workspace by its URL. 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.

Arguments

url

string

required

The destination URL of the short link.

domain

string

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

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

externalId

string | null

This is the ID of the link in your database. If set, it can be used to identify the link in the future.

prefix

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion

boolean

default: false

Whether to track conversions for the short link.

identifier

string | null

The identifier of the short link that is unique across your workspace. If set, it can be used to identify your short link for client-side click tracking.

archived

boolean

default: false

Whether the short link is archived.

publicStats

boolean

default: false

Whether the short link’s stats are publicly accessible.

tagId

string | null

The unique ID of the tag assigned to the short link. This field is deprecated – use tagIds instead.

tagIds

string

The unique IDs of the tags assigned to the short link.

tagNames

string | string[]

The unique name of the tags assigned to the short link (case insensitive).

comments

string | null

The comments for the short link.

expiresAt

string | null

The date and time when the short link will expire at.

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

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

Whether the short link uses link cloaking.

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.

doIndex

boolean

default: false

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

string | null

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.

utm_medium

string | null

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.

utm_campaign

string | null

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.

utm_term

string | null

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.

utm_content

string | null

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.

ref

string | null

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL.

programId

string | null

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

webhookIds

string[] | null

An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.

Response

id

string

required

The unique ID of the short 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.

trackConversion

boolean

default: "false"required

[BETA] Whether to track conversions for the short link.

externalId

string | null

required

This is the ID of the link in your database. If set, it can be used to identify the link in the future. Must be prefixed with ext_ when provided to links.get, links.update, and links.delete methods.

identifier

string | null

required

The identifier of the short link that is unique across your workspace. If set, it can be used to identify your short link for client-side click tracking.

url

string

required

The destination URL of the short link.

archived

boolean

default: "false"required

Whether the short link is archived.

expiresAt

string | null

required

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

expiredUrl

string | null

required

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

password

string | null

required

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

required

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

required

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

required

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

required

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

required

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

android

string | null

required

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.

tagId

string | null

required

The unique ID of the tag assigned to the short link. This field is deprecated – use tags instead.

tags

object[] | null

required

The tags assigned to the short link.

Show properties

tags.id

string

required

The unique ID of the tag.

tags.name

string

required

The name of the tag.

tags.color

string

required

The color of the tag.

webhookIds

string[]

required

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

comments

string | null

required

The comments for the short link.

shortLink

string

required

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

qrCode

string

required

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

utm_source

string | null

required

The UTM source of the short link.

utm_medium

string | null

required

The UTM medium of the short link.

utm_campaign

string | null

required

The UTM campaign of the short link.

utm_term

string | null

required

The UTM term of the short link.

utm_content

string | null

required

The UTM content of the short link.

userId

string

required

The user ID of the creator of the short link.

workspaceId

string

required

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

[BETA]: The number of leads the short link has generated.

sales

number

default: "0"required

[BETA]: The number of sales the short link has generated.

saleAmount

number

default: "0"required

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

lastClicked

string | null

required

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

createdAt

string

required

The date and time when the short link was created.

updatedAt

string

required

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

projectId

string

required

The project ID of the short link. This field is deprecated – use workspaceId instead.

programId

string | null

required

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