Skip to main content

​
Authentication

This endpoint requires authentication using a Bearer token. 
Authorization: Bearer <token>

​
Endpoint

​
method
string
required
POST
​
endpoint
string
required
/links

​
Request Body

​
url
string
required
The destination URL of the short link.Example: https://google.com
​
domain
string
The domain of the short link (without protocol). 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.
​
keyLength
number
The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength.Min: 3
Max: 190
​
externalId
string
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.Example: 123456
​
tenantId
string
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.
​
programId
string
The ID of the program the short link is associated with.
​
partnerId
string
The ID of the partner the short link is associated with.
​
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
Whether to track conversions for the short link. Defaults to false if not provided.
​
archived
boolean
Whether the short link is archived. Defaults to false if not provided.
​
tagIds
array
The unique IDs of the tags assigned to the short link.Example: ["clux0rgak00011..."]
​
tagNames
array
The unique name of the tags assigned to the short link (case insensitive).
​
folderId
string
The unique ID existing folder to assign the short link to.
​
comments
string
The comments for the short link.
​
expiresAt
string
The date and time when the short link will expire at.
​
expiredUrl
string
The URL to redirect to when the short link has expired.
​
password
string
The password required to access the destination URL of the short link.
​
proxy
boolean
Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.
​
title
string
The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og
​
description
string
The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og
​
image
string
The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og
​
video
string
The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og
​
rewrite
boolean
Whether the short link uses link cloaking. Defaults to false if not provided.
​
ios
string
The iOS destination URL for the short link for iOS device targeting.
​
android
string
The Android destination URL for the short link for Android device targeting.
​
geo
object
Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.
​
doIndex
boolean
Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex
​
utm_source
string
The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.
​
utm_medium
string
The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.
​
utm_campaign
string
The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.
​
utm_term
string
The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.
​
utm_content
string
The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.
​
ref
string
The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL.
​
webhookIds
array
An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.
​
testVariants
array
An array of A/B test URLs and the percentage of traffic to send to each URL.Example:
[
  {
    "url": "https://example.com/variant-1",
    "percentage": 50
  },
  {
    "url": "https://example.com/variant-2",
    "percentage": 50
  }
]
​
testStartedAt
string
The date and time when the tests started.
​
testCompletedAt
string
The date and time when the tests were or will be completed.

​
Response

​
id
string
The unique ID of the short link.
​
domain
string
The domain of the short link.
​
key
string
The short link slug.
​
url
string
The destination URL of the short link.
​
externalId
string
The ID of the link in your database.
​
trackConversion
boolean
Whether to track conversions for the short link.
​
archived
boolean
Whether the short link is archived.
​
expiresAt
string
The date and time when the short link will expire in ISO-8601 format.
​
expiredUrl
string
The URL to redirect to when the short link has expired.
​
password
string
The password required to access the destination URL of the short link.
​
proxy
boolean
Whether the short link uses Custom Link Previews feature.
​
title
string
The title of the short link.
​
description
string
The description of the short link.
​
image
string
The image of the short link.
​
rewrite
boolean
Whether the short link uses link cloaking.
​
doIndex
boolean
Whether to allow search engines to index the short link.
​
ios
string
The iOS destination URL for the short link.
​
android
string
The Android destination URL for the short link.
​
geo
object
Geo targeting information for the short link.
​
tags
array
The tags assigned to the short link.
​
folderId
string
The unique ID of the folder assigned to the short link.
​
comments
string
The comments for the short link.
​
shortLink
string
The full URL of the short link, including the https protocol (e.g. https://dub.sh/try).
​
qrCode
string
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
The UTM source of the short link.
​
utm_medium
string
The UTM medium of the short link.
​
utm_campaign
string
The UTM campaign of the short link.
​
utm_term
string
The UTM term of the short link.
​
utm_content
string
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
The number of clicks on the short link.
​
leads
number
The number of leads the short link has generated.
​
conversions
number
The number of leads that converted to paying customers.
​
sales
number
The total number of sales (includes recurring sales) generated by the short link.
​
saleAmount
number
The total dollar value of sales (in cents) generated by the short link.
​
lastClicked
string
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.
curl -X POST https://api.dub.co/links \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://google.com",
    "domain": "dub.sh",
    "key": "try"
  }'

{
  "id": "clux0rgak00011...",
  "domain": "dub.sh",
  "key": "try",
  "url": "https://google.com",
  "archived": false,
  "expiresAt": null,
  "expiredUrl": null,
  "password": null,
  "proxy": false,
  "title": null,
  "description": null,
  "image": null,
  "video": null,
  "rewrite": false,
  "doIndex": false,
  "ios": null,
  "android": null,
  "geo": null,
  "publicStats": false,
  "tags": [],
  "folderId": null,
  "comments": null,
  "shortLink": "https://dub.sh/try",
  "qrCode": "https://api.dub.co/qr?url=https://dub.sh/try",
  "utm_source": null,
  "utm_medium": null,
  "utm_campaign": null,
  "utm_term": null,
  "utm_content": null,
  "userId": "user_123",
  "workspaceId": "ws_123",
  "clicks": 0,
  "leads": 0,
  "conversions": 0,
  "sales": 0,
  "saleAmount": 0,
  "lastClicked": null,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "trackConversion": false,
  "externalId": null,
  "tenantId": null,
  "programId": null,
  "partnerId": null,
  "webhookIds": []
}

Build docs developers (and LLMs) love

Get started for freeTalk to us