Upsert a link for a partner

PUT

partners

links

upsert

Python

from dub import Dub


with Dub(
    token="DUB_API_KEY",
) as d_client:

    res = d_client.partners.upsert_link(request={
        "link_props": {
            "external_id": "123456",
            "tag_ids": [
                "clux0rgak00011...",
            ],
            "test_variants": [
                {
                    "url": "https://example.com/variant-1",
                    "percentage": 50,
                },
                {
                    "url": "https://example.com/variant-2",
                    "percentage": 50,
                },
            ],
        },
    })

    assert res is not None

    # Handle response
    print(res)

{
  "id": "<string>",
  "domain": "<string>",
  "key": "<string>",
  "url": "<string>",
  "trackConversion": false,
  "externalId": "<string>",
  "tenantId": "<string>",
  "programId": "<string>",
  "partnerId": "<string>",
  "archived": false,
  "expiresAt": "<string>",
  "expiredUrl": "<string>",
  "password": "<string>",
  "proxy": false,
  "title": "<string>",
  "description": "<string>",
  "image": "<string>",
  "video": "<string>",
  "rewrite": false,
  "doIndex": false,
  "ios": "<string>",
  "android": "<string>",
  "geo": {},
  "publicStats": false,
  "tags": [
    {
      "id": "<string>",
      "name": "<string>",
      "color": "red"
    }
  ],
  "folderId": "<string>",
  "webhookIds": [
    "<string>"
  ],
  "comments": "<string>",
  "shortLink": "<string>",
  "qrCode": "<string>",
  "utm_source": "<string>",
  "utm_medium": "<string>",
  "utm_campaign": "<string>",
  "utm_term": "<string>",
  "utm_content": "<string>",
  "testVariants": [
    {
      "url": "https://example.com/variant-1",
      "percentage": 50
    },
    {
      "url": "https://example.com/variant-2",
      "percentage": 50
    }
  ],
  "testStartedAt": "<string>",
  "testCompletedAt": "<string>",
  "userId": "<string>",
  "workspaceId": "<string>",
  "clicks": 0,
  "leads": 0,
  "conversions": 0,
  "sales": 0,
  "saleAmount": 0,
  "lastClicked": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "tagId": "<string>",
  "projectId": "<string>"
}

Partners endpoints require an Advanced plan subscription or higher.

Authorizations

Authorization

string

header

required

Default authentication mechanism

Body

application/json

partnerId

string | null

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

string | null

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

url

string | null

The URL to shorten (if not provided, the program's default URL will be used). Will throw an error if the domain doesn't match the program's default URL domain.

key

string

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

Maximum length: 190

comments

string | null

The comments for the short link.

linkProps

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

Show child attributes

Response

The upserted partner link

string

required

The unique ID of the short 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<uri>

required

The destination URL of the short link.

trackConversion

boolean

default:false

required

Whether to track conversions for the short link.

externalId

string | null

required

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

required

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 | null

required

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

partnerId

string | null

required

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

archived

boolean

default:false

required

Whether the short link is archived.

expiresAt

string | null

required

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

expiredUrl

string<uri> | null

required

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

password

string | null

required

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

proxy

boolean

default:false

required

Whether the short link uses Custom Link Previews feature.

title

string | null

required

The title of the short link. Will be used for Custom Link Previews if proxy is true.

description

string | null

required

The description of the short link. Will be used for Custom Link Previews if proxy is true.

image

string | null

required

The image of the short link. Will be used for Custom Link Previews if proxy is true.

video

string | null

required

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

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

required

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

android

string | null

required

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

geo

object | null

required

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

Show child attributes

publicStats

boolean

default:false

required

Whether the short link's stats are publicly accessible.

tags

Tag · object[] | null

required

The tags assigned to the short link.

Show child attributes

folderId

string | null

required

The unique ID of the folder assigned to the short link.

webhookIds

string[]

required

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

comments

string | null

required

The comments for the short link.

shortLink

string<uri>

required

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

qrCode

string<uri>

required

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 | null

required

The UTM source of the short link.

utm_medium

string | null

required

The UTM medium of the short link.

utm_campaign

string | null

required

The UTM campaign of the short link.

utm_term

string | null

required

The UTM term of the short link.

utm_content

string | null

required

The UTM content of the short link.

userId

string | null

required

The user ID of the creator of the short link.

workspaceId

string

required

The workspace ID of the short link.

clicks

number

default:0

required

The number of clicks on the short link.

leads

number

default:0

required

The number of leads the short link has generated.

conversions

number

default:0

required

The number of leads that converted to paying customers.

sales

number

default:0

required

The total number of sales (includes recurring sales) generated by the short link.

saleAmount

number

default:0

required

The total dollar value of sales (in cents) generated by the short link.

lastClicked

string | null

required

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

createdAt

string

required

The date and time when the short link was created.

updatedAt

string

required

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

tagId

string | null

required

deprecated

Deprecated: Use tags instead. The unique ID of the tag assigned to the short link.

projectId

string

required

deprecated

Deprecated: Use workspaceId instead. The project ID of the short link.

testVariants

object[] | null

An array of A/B test URLs and the percentage of traffic to send to each URL.

Required array length: 2 - 4 elements

Show child attributes

Example:

[
  {
    "url": "https://example.com/variant-1",
    "percentage": 50
  },
  {
    "url": "https://example.com/variant-2",
    "percentage": 50
  }
]

testStartedAt

string | null

The date and time when the tests started.

testCompletedAt

string | null

The date and time when the tests were or will be completed.

Retrieve a partner's linksRetrieve a partner's links by their partner ID or tenant ID.

Python

from dub import Dub


with Dub(
    token="DUB_API_KEY",
) as d_client:

    res = d_client.partners.upsert_link(request={
        "link_props": {
            "external_id": "123456",
            "tag_ids": [
                "clux0rgak00011...",
            ],
            "test_variants": [
                {
                    "url": "https://example.com/variant-1",
                    "percentage": 50,
                },
                {
                    "url": "https://example.com/variant-2",
                    "percentage": 50,
                },
            ],
        },
    })

    assert res is not None

    # Handle response
    print(res)

{
  "id": "<string>",
  "domain": "<string>",
  "key": "<string>",
  "url": "<string>",
  "trackConversion": false,
  "externalId": "<string>",
  "tenantId": "<string>",
  "programId": "<string>",
  "partnerId": "<string>",
  "archived": false,
  "expiresAt": "<string>",
  "expiredUrl": "<string>",
  "password": "<string>",
  "proxy": false,
  "title": "<string>",
  "description": "<string>",
  "image": "<string>",
  "video": "<string>",
  "rewrite": false,
  "doIndex": false,
  "ios": "<string>",
  "android": "<string>",
  "geo": {},
  "publicStats": false,
  "tags": [
    {
      "id": "<string>",
      "name": "<string>",
      "color": "red"
    }
  ],
  "folderId": "<string>",
  "webhookIds": [
    "<string>"
  ],
  "comments": "<string>",
  "shortLink": "<string>",
  "qrCode": "<string>",
  "utm_source": "<string>",
  "utm_medium": "<string>",
  "utm_campaign": "<string>",
  "utm_term": "<string>",
  "utm_content": "<string>",
  "testVariants": [
    {
      "url": "https://example.com/variant-1",
      "percentage": 50
    },
    {
      "url": "https://example.com/variant-2",
      "percentage": 50
    }
  ],
  "testStartedAt": "<string>",
  "testCompletedAt": "<string>",
  "userId": "<string>",
  "workspaceId": "<string>",
  "clicks": 0,
  "leads": 0,
  "conversions": 0,
  "sales": 0,
  "saleAmount": 0,
  "lastClicked": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "tagId": "<string>",
  "projectId": "<string>"
}

Overview

SDKs

APIs

Authorizations

Body

Response