Dub

Use Dub to create and manage short links with custom domains, slugs, UTM parameters, and link-preview titles and descriptions. Upsert Link creates or updates a link by destination URL; lookup and deletion also support the identifiers documented for each action.

List actions support filtering, sorting, and pagination. Analytics report clicks, leads, and sales, with grouping by time, geography, device, browser, referrer, and other supported dimensions.

Use the block

Create, update, delete, or list short links with custom domains, slugs, link-preview titles and descriptions, and UTM parameters. Retrieve click, lead, and sales analytics.

Actions

Dub Create Link

Create a new short link with Dub. Supports custom domains, slugs, UTM parameters, and more.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
url	string	Yes	The destination URL of the short link
domain	string	No	Custom domain for the short link (defaults to dub.sh)
key	string	No	Custom slug for the short link (randomly generated if not provided)
externalId	string	No	External ID for the link in your database
tenantId	string	No	Tenant ID for grouping links created on behalf of a customer/tenant
folderId	string	No	Folder ID to organize the link into
trackConversion	boolean	No	Whether to track conversions (leads/sales) for the short link
tagIds	string	No	Comma-separated tag IDs to assign to the link
comments	string	No	Comments for the short link
expiresAt	string	No	Expiration date in ISO 8601 format
password	string	No	Password to protect the short link
rewrite	boolean	No	Whether to enable link cloaking
archived	boolean	No	Whether to archive the link
title	string	No	Custom OG title for the link preview
description	string	No	Custom OG description for the link preview
utm_source	string	No	UTM source parameter
utm_medium	string	No	UTM medium parameter
utm_campaign	string	No	UTM campaign parameter
utm_term	string	No	UTM term parameter
utm_content	string	No	UTM content parameter

Output

Parameter	Type	Description
id	string	Unique ID of the created link
domain	string	Domain of the short link
key	string	Slug of the short link
url	string	Destination URL
shortLink	string	Full short link URL
qrCode	string	QR code URL for the short link
archived	boolean	Whether the link is archived
externalId	string	External ID
title	string	OG title
description	string	OG description
tags	json	Tags assigned to the link (id, name, color)
folderId	string	Folder the link is organized into
tenantId	string	Tenant ID associated with the link
trackConversion	boolean	Whether conversion tracking is enabled
clicks	number	Number of clicks
leads	number	Number of leads
conversions	number	Number of conversions
sales	number	Number of sales
saleAmount	number	Total sale amount in cents
lastClicked	string	Last clicked timestamp
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp
utm_source	string	UTM source parameter
utm_medium	string	UTM medium parameter
utm_campaign	string	UTM campaign parameter
utm_term	string	UTM term parameter
utm_content	string	UTM content parameter

Dub Upsert Link

Create or update a short link by its URL. If a link with the same URL already exists, update it. Otherwise, create a new link.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
url	string	Yes	The destination URL of the short link
domain	string	No	Custom domain for the short link (defaults to dub.sh)
key	string	No	Custom slug for the short link (randomly generated if not provided)
externalId	string	No	External ID for the link in your database
tenantId	string	No	Tenant ID for grouping links created on behalf of a customer/tenant
folderId	string	No	Folder ID to organize the link into
trackConversion	boolean	No	Whether to track conversions (leads/sales) for the short link
tagIds	string	No	Comma-separated tag IDs to assign to the link
comments	string	No	Comments for the short link
expiresAt	string	No	Expiration date in ISO 8601 format
password	string	No	Password to protect the short link
rewrite	boolean	No	Whether to enable link cloaking
archived	boolean	No	Whether to archive the link
title	string	No	Custom OG title for the link preview
description	string	No	Custom OG description for the link preview
utm_source	string	No	UTM source parameter
utm_medium	string	No	UTM medium parameter
utm_campaign	string	No	UTM campaign parameter
utm_term	string	No	UTM term parameter
utm_content	string	No	UTM content parameter

Output

Parameter	Type	Description
id	string	Unique ID of the link
domain	string	Domain of the short link
key	string	Slug of the short link
url	string	Destination URL
shortLink	string	Full short link URL
qrCode	string	QR code URL for the short link
archived	boolean	Whether the link is archived
externalId	string	External ID
title	string	OG title
description	string	OG description
tags	json	Tags assigned to the link (id, name, color)
folderId	string	Folder the link is organized into
tenantId	string	Tenant ID associated with the link
trackConversion	boolean	Whether conversion tracking is enabled
clicks	number	Number of clicks
leads	number	Number of leads
conversions	number	Number of conversions
sales	number	Number of sales
saleAmount	number	Total sale amount in cents
lastClicked	string	Last clicked timestamp
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp
utm_source	string	UTM source parameter
utm_medium	string	UTM medium parameter
utm_campaign	string	UTM campaign parameter
utm_term	string	UTM term parameter
utm_content	string	UTM content parameter

Dub Get Link

Retrieve information about a short link by its link ID, external ID, or domain + key combination.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
linkId	string	No	The unique ID of the short link
externalId	string	No	The external ID of the link in your database
domain	string	No	The domain of the link (use with key)
key	string	No	The slug of the link (use with domain)

Output

Parameter	Type	Description
id	string	Unique ID of the link
domain	string	Domain of the short link
key	string	Slug of the short link
url	string	Destination URL
shortLink	string	Full short link URL
qrCode	string	QR code URL for the short link
archived	boolean	Whether the link is archived
externalId	string	External ID
title	string	OG title
description	string	OG description
tags	json	Tags assigned to the link (id, name, color)
folderId	string	Folder the link is organized into
tenantId	string	Tenant ID associated with the link
trackConversion	boolean	Whether conversion tracking is enabled
clicks	number	Number of clicks
leads	number	Number of leads
conversions	number	Number of conversions
sales	number	Number of sales
saleAmount	number	Total sale amount in cents
lastClicked	string	Last clicked timestamp
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp
utm_source	string	UTM source parameter
utm_medium	string	UTM medium parameter
utm_campaign	string	UTM campaign parameter
utm_term	string	UTM term parameter
utm_content	string	UTM content parameter

Dub Update Link

Update an existing short link's destination URL, domain, slug, link-preview title and description, UTM parameters, and other supported settings.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
linkId	string	Yes	The link ID or external ID prefixed with ext_
url	string	No	New destination URL
domain	string	No	New custom domain
key	string	No	New custom slug
title	string	No	Custom OG title
description	string	No	Custom OG description
externalId	string	No	External ID for the link
tenantId	string	No	Tenant ID for grouping links created on behalf of a customer/tenant
folderId	string	No	Folder ID to organize the link into
trackConversion	boolean	No	Whether to track conversions (leads/sales) for the short link
tagIds	string	No	Comma-separated tag IDs
comments	string	No	Comments for the short link
expiresAt	string	No	Expiration date in ISO 8601 format
password	string	No	Password to protect the link
rewrite	boolean	No	Whether to enable link cloaking
archived	boolean	No	Whether to archive the link
utm_source	string	No	UTM source parameter
utm_medium	string	No	UTM medium parameter
utm_campaign	string	No	UTM campaign parameter
utm_term	string	No	UTM term parameter
utm_content	string	No	UTM content parameter

Output

Parameter	Type	Description
id	string	Unique ID of the updated link
domain	string	Domain of the short link
key	string	Slug of the short link
url	string	Destination URL
shortLink	string	Full short link URL
qrCode	string	QR code URL for the short link
archived	boolean	Whether the link is archived
externalId	string	External ID
title	string	OG title
description	string	OG description
tags	json	Tags assigned to the link (id, name, color)
folderId	string	Folder the link is organized into
tenantId	string	Tenant ID associated with the link
trackConversion	boolean	Whether conversion tracking is enabled
clicks	number	Number of clicks
leads	number	Number of leads
conversions	number	Number of conversions
sales	number	Number of sales
saleAmount	number	Total sale amount in cents
lastClicked	string	Last clicked timestamp
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp
utm_source	string	UTM source parameter
utm_medium	string	UTM medium parameter
utm_campaign	string	UTM campaign parameter
utm_term	string	UTM term parameter
utm_content	string	UTM content parameter

Dub Delete Link

Delete a short link by its link ID or external ID (prefixed with ext_).

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
linkId	string	Yes	The link ID or external ID prefixed with ext_

Output

Parameter	Type	Description
id	string	ID of the deleted link

Dub List Links

Retrieve a paginated list of short links for the authenticated workspace. Supports filtering by domain, search query, tags, and sorting.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
domain	string	No	Filter by domain
search	string	No	Search query matched against the short link slug and destination URL
tagIds	string	No	Comma-separated tag IDs to filter by
tenantId	string	No	Filter by tenant ID
folderId	string	No	Filter by folder ID
showArchived	boolean	No	Whether to include archived links (defaults to false)
page	number	No	Page number (deprecated by Dub in favor of startingAfter/endingBefore)
pageSize	number	No	Number of links per page (default: 100, max: 100)
startingAfter	string	No	Cursor: fetch results after this link ID
endingBefore	string	No	Cursor: fetch results before this link ID

Output

Parameter	Type	Description
links	json	Array of link objects (id, domain, key, url, shortLink, clicks, tags, createdAt)
count	number	Number of links returned

Dub Count Links

Retrieve the number of short links for the authenticated workspace, optionally filtered and grouped by domain, tag, user, or folder.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
domain	string	No	Filter by domain
search	string	No	Search query matched against the short link slug and destination URL
tagIds	string	No	Comma-separated tag IDs to filter by
tagNames	string	No	Comma-separated tag names to filter by (case-insensitive)
folderId	string	No	Filter by folder ID
showArchived	boolean	No	Whether to include archived links (defaults to false)
groupBy	string	No	Group counts by: domain, tagId, userId, or folderId

Output

Parameter	Type	Description
count	number	Total number of links matching the filters
groups	json	Per-group counts when groupBy is set (e.g. [{ domain, count }])

Dub Bulk Create Links

Create up to 100 short links in a single request. Returns the created links alongside any per-link errors.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
links	json	Yes	JSON array of link objects to create. Each object requires a "url" and may include domain, key, tagIds, and other link fields (max 100).

Output

Parameter	Type	Description
created	json	Array of successfully created link objects
errors	json	Array of per-link errors ({ link, error, code }) for links that failed
count	number	Number of links successfully created

Dub Bulk Update Links

Apply the same set of field updates to up to 100 links at once, selected by link IDs or external IDs.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
linkIds	string	No	Comma-separated link IDs to update (max 100, takes precedence over externalIds)
externalIds	string	No	Comma-separated external IDs to update (max 100)
data	json	Yes	JSON object of fields to apply to every selected link (e.g. { "archived": true, "tagIds": ["..."] })

Output

Parameter	Type	Description
updated	json	Array of updated link objects
count	number	Number of links updated

Dub Bulk Delete Links

Delete up to 100 short links in a single request by their link IDs. Non-existing IDs are ignored.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
linkIds	string	Yes	Comma-separated link IDs to delete (max 100)

Output

Parameter	Type	Description
deletedCount	number	Number of links that were deleted

Dub Get Analytics

Retrieve analytics for links including clicks, leads, and sales. Supports filtering by link, time range, and grouping by various dimensions.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
event	string	No	Event type: clicks (default), leads, sales, or composite
groupBy	string	No	Group results by: count (default), timeseries, countries, cities, devices, browsers, os, referers, top_links, top_urls
linkId	string	No	Filter by link ID
externalId	string	No	Filter by external ID (prefix with ext_)
domain	string	No	Filter by domain
interval	string	No	Time interval: 24h (default), 7d, 30d, 90d, 1y, mtd, qtd, ytd, or all
start	string	No	Start date/time in ISO 8601 format (overrides interval)
end	string	No	End date/time in ISO 8601 format (defaults to now)
country	string	No	Filter by country (ISO 3166-1 alpha-2 code)
timezone	string	No	IANA timezone for timeseries data (defaults to UTC)

Output

Parameter	Type	Description
clicks	number	Total number of clicks
leads	number	Total number of leads
sales	number	Total number of sales
saleAmount	number	Total sale amount in cents
data	json	Grouped analytics data (timeseries, countries, devices, etc.)

Dub List Events

Retrieve a paginated stream of individual click, lead, and sale events for links, with filtering by link, time range, and location.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
event	string	No	Event type: clicks (default), leads, or sales
linkId	string	No	Filter by link ID
externalId	string	No	Filter by external ID (prefix with ext_)
domain	string	No	Filter by domain
interval	string	No	Time interval: 24h (default), 7d, 30d, 90d, 1y, mtd, qtd, ytd, or all
start	string	No	Start date/time in ISO 8601 format (overrides interval)
end	string	No	End date/time in ISO 8601 format (defaults to now)
country	string	No	Filter by country (ISO 3166-1 alpha-2 code)
timezone	string	No	IANA timezone for event timestamps (defaults to UTC)
page	number	No	Page number (default: 1)
limit	number	No	Number of events per page (default: 100, max: 1000)
sortOrder	string	No	Sort order: desc (default) or asc

Output

Parameter	Type	Description
events	json	Array of event objects (event, timestamp, click, link, and customer/sale data when applicable)
count	number	Number of events returned

Dub Get QR Code

Generate a customizable QR code (PNG) for a short link, with control over size, error correction, colors, and margin.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
url	string	Yes	The short link URL to encode in the QR code
logo	string	No	URL of a custom logo to embed in the QR code (requires a paid Dub plan)
size	number	No	QR code size in pixels (default: 600)
level	string	No	Error correction level: L (default), M, Q, or H
fgColor	string	No	Foreground color in hex (default: #000000)
bgColor	string	No	Background color in hex (default: #FFFFFF)
hideLogo	boolean	No	Whether to hide the logo in the center of the QR code (default: false)
margin	number	No	Margin (quiet zone) around the QR code (default: 2)

Output

Parameter	Type	Description
file	file	Generated QR code image stored in execution files

Dub List Domains

Retrieve the custom domains registered in the workspace, so links can be created against the right domain.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
archived	boolean	No	Whether to include archived domains (defaults to false)
search	string	No	Search by domain name
page	number	No	Page number (default: 1)
pageSize	number	No	Number of domains per page (default: 50, max: 50)

Output

Parameter	Type	Description
domains	json	Array of domain objects (slug, verified, primary, archived)
count	number	Number of domains returned

Dub List Tags

Retrieve the tags defined in the workspace, so the right tag IDs can be assigned to links.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
search	string	No	Search by tag name
sortBy	string	No	Field to sort by: name (default) or createdAt
sortOrder	string	No	Sort order: asc (default) or desc
page	number	No	Page number (default: 1)
pageSize	number	No	Number of tags per page (default: 100, max: 100)

Output

Parameter	Type	Description
tags	json	Array of tag objects (id, name, color)
count	number	Number of tags returned

Dub Create Tag

Create a new tag in the workspace for organizing and filtering short links.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
name	string	Yes	The name of the tag to create (1-50 characters)
color	string	No	Tag color: red, yellow, green, blue, purple, brown, gray, or pink (random if omitted)

Output

Parameter	Type	Description
id	string	Unique ID of the created tag
name	string	Name of the tag
color	string	Color assigned to the tag

Dub List Folders

Retrieve the folders defined in the workspace, so the right folder ID can be used to organize links.

Inputs and outputs

Input

Parameter	Type	Required	Description
apiKey	string	Yes	Dub API key
search	string	No	Search by folder name
page	number	No	Page number (default: 1)
pageSize	number	No	Number of folders per page (default: 50, max: 50)

Output

Parameter	Type	Description
folders	json	Array of folder objects (id, name, accessLevel)
count	number	Number of folders returned