Introduction

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_.

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

string

required

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

string

required

The destination URL of the short link.

string

required

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

boolean

default:"false"

Whether to track conversions for the short link.

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.

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.

boolean

default:"false"

required

Whether the short link is archived.

string | null

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

string | null

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

string | null

The password required to access the destination URL of the short link.

boolean

default:"false"

required

Whether the short link uses Custom Social Media Cards feature.

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.

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.

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.

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

boolean

default:"false"

required

Whether the short link uses link cloaking.

boolean

default:"false"

required

Whether to allow search engines to index the short link.

string | null

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

string | null

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

boolean

default:"false"

required

Whether the short link’s stats are publicly accessible.

object[] | null

The tags assigned to the short link.

Show properties

string

The unique ID of the tag.

string

The name of the tag.

string

The color of the tag.

string[]

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

string | null

The comments for the short link.

string

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

string | null

The UTM source of the short link.

string | null

The UTM medium of the short link.

string | null

The UTM campaign of the short link.

string | null

The UTM term of the short link.

string | null

The UTM content of the short link.

string

The user ID of the creator of the short link.

string

The workspace ID of the short link.

number

default:"0"

required

The number of clicks on the short link.

number

default:"0"

required

The number of leads the short link has generated.

number

default:"0"

required

The number of sales the short link has generated.

number

default:"0"

required

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

string | null

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

string

The date and time when the short link was created.

string

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

string | null

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

You can use the various Dub SDKs to programmatically manage your links.

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"}'

Getting Started

Concepts

Conversions

Integrations

Open source

The link model

Create a link

Update a link

Upsert a link

​The link model

​Create a link

​Update a link

​Upsert a link

The link model

Create a link

Update a link

Upsert a link