# Dub (/integrations/dub)





{/* MANUAL-CONTENT-START:intro */}

Use [Dub](https://dub.co/) 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.

{/* MANUAL-CONTENT-END */}

## Use the block [#usage-instructions]

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 [#actions]

### Dub Create Link [#dub-create-link]

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

<ReferenceDetails>
  #### Input [#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 [#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 |
</ReferenceDetails>

### Dub Upsert Link [#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.

<ReferenceDetails>
  #### Input [#input-1]

  | 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 [#output-1]

  | 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 |
</ReferenceDetails>

### Dub Get Link [#dub-get-link]

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

<ReferenceDetails>
  #### Input [#input-2]

  | 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 [#output-2]

  | 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 |
</ReferenceDetails>

### Dub Update Link [#dub-update-link]

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

<ReferenceDetails>
  #### Input [#input-3]

  | 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 [#output-3]

  | 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 |
</ReferenceDetails>

### Dub Delete Link [#dub-delete-link]

Delete a short link by its link ID or external ID (prefixed with ext\_).

<ReferenceDetails>
  #### Input [#input-4]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | Dub API key |
  | `linkId` | string | Yes | The link ID or external ID prefixed with ext\_ |

  #### Output [#output-4]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | ID of the deleted link |
</ReferenceDetails>

### Dub List Links [#dub-list-links]

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

<ReferenceDetails>
  #### Input [#input-5]

  | 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 [#output-5]

  | Parameter | Type | Description |
  | - | - | - |
  | `links` | json | Array of link objects (id, domain, key, url, shortLink, clicks, tags, createdAt) |
  | `count` | number | Number of links returned |
</ReferenceDetails>

### Dub Count Links [#dub-count-links]

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

<ReferenceDetails>
  #### Input [#input-6]

  | 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 [#output-6]

  | 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 }]) |
</ReferenceDetails>

### Dub Bulk Create Links [#dub-bulk-create-links]

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

<ReferenceDetails>
  #### Input [#input-7]

  | 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 [#output-7]

  | 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 |
</ReferenceDetails>

### Dub Bulk Update Links [#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.

<ReferenceDetails>
  #### Input [#input-8]

  | 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 [#output-8]

  | Parameter | Type | Description |
  | - | - | - |
  | `updated` | json | Array of updated link objects |
  | `count` | number | Number of links updated |
</ReferenceDetails>

### Dub Bulk Delete Links [#dub-bulk-delete-links]

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

<ReferenceDetails>
  #### Input [#input-9]

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

  #### Output [#output-9]

  | Parameter | Type | Description |
  | - | - | - |
  | `deletedCount` | number | Number of links that were deleted |
</ReferenceDetails>

### Dub Get Analytics [#dub-get-analytics]

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

<ReferenceDetails>
  #### Input [#input-10]

  | 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 [#output-10]

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

### Dub List Events [#dub-list-events]

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

<ReferenceDetails>
  #### Input [#input-11]

  | 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 [#output-11]

  | 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 |
</ReferenceDetails>

### Dub Get QR Code [#dub-get-qr-code]

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

<ReferenceDetails>
  #### Input [#input-12]

  | 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 [#output-12]

  | Parameter | Type | Description |
  | - | - | - |
  | `file` | file | Generated QR code image stored in execution files |
</ReferenceDetails>

### Dub List Domains [#dub-list-domains]

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

<ReferenceDetails>
  #### Input [#input-13]

  | 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 [#output-13]

  | Parameter | Type | Description |
  | - | - | - |
  | `domains` | json | Array of domain objects (slug, verified, primary, archived) |
  | `count` | number | Number of domains returned |
</ReferenceDetails>

### Dub List Tags [#dub-list-tags]

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

<ReferenceDetails>
  #### Input [#input-14]

  | 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 [#output-14]

  | Parameter | Type | Description |
  | - | - | - |
  | `tags` | json | Array of tag objects (id, name, color) |
  | `count` | number | Number of tags returned |
</ReferenceDetails>

### Dub Create Tag [#dub-create-tag]

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

<ReferenceDetails>
  #### Input [#input-15]

  | 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 [#output-15]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | Unique ID of the created tag |
  | `name` | string | Name of the tag |
  | `color` | string | Color assigned to the tag |
</ReferenceDetails>

### Dub List Folders [#dub-list-folders]

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

<ReferenceDetails>
  #### Input [#input-16]

  | 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 [#output-16]

  | Parameter | Type | Description |
  | - | - | - |
  | `folders` | json | Array of folder objects (id, name, accessLevel) |
  | `count` | number | Number of folders returned |
</ReferenceDetails>