Introduction - Dub Docs

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
`id`	The unique identifier of the link (prefixed with `link_`)	`link_eBKA4MT44XnI17hYLchkjUOd`
`url`	The destination URL of the link	`https://dub.co/home`
`shortLink`	The shortened version of the link (including https)	`https://dub.link/claim`
`domain`	The domain of the link	`dub.link`
`key`	The 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

string

required

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

url

string

required

The destination URL of the short link.

shortLink

string

required

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

trackConversion

boolean

default:"false"

Whether to track conversions for the short link.

externalId

string | null

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.

tenantId

string | null

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.

archived

boolean

default:"false"

required

Whether the short link is archived.

expiresAt

string | null

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

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"

required

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"

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

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.

publicStats

boolean

default:"false"

required

Whether the short link’s stats are publicly accessible.

Create a link

The url field, representing the destination URL, is the sole mandatory parameter required for the creation of a new short link.

import { Dub } from "dub";

export const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const link = await dub.links.create({
  url: "https://google.com",
});

package main

import(
  "context"
  dubgo "github.com/dubinc/dub-go"
  "github.com/dubinc/dub-go/models/operations"
  "log"
  "os"
)

func main() {
  ctx := context.Background()

  s := dubgo.New(
    dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
  )

  res, err := s.Links.Create(ctx, &operations.CreateLinkRequestBody{
    URL: "https://google.com",
  })

  if err != nil {
    log.Fatal(err)
  }

  if res != nil {
    // handle response
  }
}

import os
import dub
from dub.models import operations

d = dub.Dub(
  token=os.environ['DUB_API_KEY'],
)

res = d.links.create(request={
  "url": "https://google.com",
})

require 'dub'

s = ::OpenApiSDK::Dub.new
s.config_security(
  ::OpenApiSDK::Shared::Security.new(
    token: "DUB_API_KEY",
  )
)

req = ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
  url: "https://google.com",
)

declare(strict_types=1);

require 'vendor/autoload.php';

use Dub;
use Dub\Models\Operations;

$sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

$request = new Operations\CreateLinkRequestBody(
  url: 'https://google.com',
);

$response = $sdk->links->create(
  request: $request
);

curl --request POST \
  --url https://api.dub.co/links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://google.com"}'

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.

import { Dub } from "dub";

export const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const link = await dub.links.update("link_eBKA4MT44XnI17hYLchkjUOd", {
  url: "https://www.google.uk", // new URL
});

package main

import(
  "context"
  dubgo "github.com/dubinc/dub-go"
  "github.com/dubinc/dub-go/models/operations"
  "log"
  "os"
)

func main() {
  ctx := context.Background()

  s := dubgo.New(
    dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
  )

  res, err := s.Links.Update(ctx, "link_eBKA4MT44XnI17hYLchkjUOd", &operations.UpdateLinkRequestBody{
    URL: "https://www.google.uk", // new URL
  })

  if err != nil {
    log.Fatal(err)
  }

  if res != nil {
    // handle response
  }
}

import os
import dub
from dub.models import operations

d = dub.Dub(
  token=os.environ['DUB_API_KEY'],
)

res = dub.links.update(link_id="link_eBKA4MT44XnI17hYLchkjUOd", request_body={
  "url": "https://www.google.uk", // new URL
})

require 'dub'

s = ::OpenApiSDK::Dub.new
s.config_security(
  ::OpenApiSDK::Shared::Security.new(
    token: "DUB_API_KEY",
  )
)

res = s.links.update(link_id="link_eBKA4MT44XnI17hYLchkjUOd", request_body={
  "url": "https://www.google.uk", // new URL
})

declare(strict_types=1);

require 'vendor/autoload.php';

use Dub;
use Dub\Models\Operations;

$sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

$requestBody = new Operations\UpdateLinkRequestBody(
  url: 'https://www.google.uk', // new URL
);

$response = $sdk->links->update(
  linkId: 'link_eBKA4MT44XnI17hYLchkjUOd',
  requestBody: $requestBody
);

curl --request PATCH \
  --url https://api.dub.co/links/link_eBKA4MT44XnI17hYLchkjUOd \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://www.google.uk"}'

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.

import { Dub } from "dub";

export const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const link = await dub.links.upsert({
  url: "https://google.com", // will always be the same short link
});

package main

import(
  "context"
  dubgo "github.com/dubinc/dub-go"
  "github.com/dubinc/dub-go/models/operations"
  "log"
  "os"
)

func main() {
  ctx := context.Background()

  s := dubgo.New(
    dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
  )

  res, err := s.Links.Upsert(ctx, &operations.UpsertLinkRequestBody{
    URL: "https://google.com",
  })

  if err != nil {
    log.Fatal(err)
  }

  if res != nil {
    // handle response
  }
}

import os
import dub
from dub.models import operations

d = dub.Dub(
  token=os.environ['DUB_API_KEY'],
)

res = d.links.upsert(request={
  "url": "https://google.com",
})

require 'dub'

s = ::OpenApiSDK::Dub.new
s.config_security(
  ::OpenApiSDK::Shared::Security.new(
    token: "DUB_API_KEY",
  )
)

req = ::OpenApiSDK::Operations::UpsertLinkRequestBody.new(
  url: "https://google.com",
)

declare(strict_types=1);

require 'vendor/autoload.php';

use Dub;
use Dub\Models\Operations;

$sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

$request = new Operations\UpsertLinkRequestBody(
  url: 'https://google.com',
);

$response = $sdk->links->upsert(
  request: $request
);

curl --request POST \
  --url https://api.dub.co/links/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://google.com"}'

​The link model

​Create a link

​Update a link

​Upsert a link

The link model

Create a link

Update a link

Upsert a link