Dub Links API – 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_1KJ1H3PZGE081A22TC6PTQYJP`
`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 here. 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"}'

Check out the full API reference for the link creation endpoint.

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_1KJ1H3PZGE081A22TC6PTQYJP", {
  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_1KJ1H3PZGE081A22TC6PTQYJP", &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_1KJ1H3PZGE081A22TC6PTQYJP", 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_1KJ1H3PZGE081A22TC6PTQYJP", 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_1KJ1H3PZGE081A22TC6PTQYJP',
  requestBody: $requestBody
);

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

Check out the full API reference for the link update endpoint.

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

Check out the full API reference for the link upsert endpoint.

GETTING STARTED

CONCEPTS

INTEGRATIONS

OPEN SOURCE

Introduction

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