Create a link for a partner

Create a link for a partner that is enrolled in your program.

1 min read

post/partners/links

Request example

from dub import Dub


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

    res = d_client.partners.create_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,
                },
            ],
        },
    })

    # Handle response
    print(res)

Response

{
  "id": "<string>",
  "domain": "<string>",
  "key": "<string>",
  "url": "<string>",
  "trackConversion": false,
  "externalId": "<string>",
  "tenantId": "<string>",
  "programId": "<string>",
  "partnerId": "<string>",
  "archived": false,
  "expiresAt": "<string>",
  "expiredUrl": "<string>",
  "disabledAt": "<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>",
  "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>",
  "webhookIds": [
    "<string>"
  ]
}

post/partners/links

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Body

application/json

partnerIdstring#

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

tenantIdstring#

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

urlstring#

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.

Length: max 32000

keystring#

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

Length: max 190

commentsstring#

The comments for the short link.

linkPropsobject#

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

externalIdstring#

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.

Length: 1–255

tenantIdstring#

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.

Length: max 255

prefixstring#

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archivedboolean#

Whether the short link is archived. Defaults to false if not provided.

tagIdsstring · string[]#

The unique IDs of the tags assigned to the short link.

Show child attributes

Any of

tagNamesstring · string[]#

The unique name of the tags assigned to the short link (case insensitive).

Show child attributes

Any of

commentsstring#

The comments for the short link.

expiresAtstring#

The date and time when the short link will expire at.

expiredUrlstring#

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

Length: max 32000

passwordstring#

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

proxyboolean#

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

titlestring#

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

descriptionstring#

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

imagestring#

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

videostring#

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewriteboolean#

Whether the short link uses link cloaking. Defaults to false if not provided.

iosstring#

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

Length: max 32000

androidstring#

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

Length: max 32000

doIndexboolean#

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariantsobject[]#

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

Items: 2–4

Show child attributes

urlstringrequired#

percentagenumberrequired#

Range: 10–90

testStartedAtstring#

The date and time when the tests started.

testCompletedAtstring#

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

Responses

application/json

The created partner link

idstringrequired#

The unique ID of the short link.

domainstringrequired#

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

keystringrequired#

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

urlstringrequired#

The destination URL of the short link.

trackConversionbooleanrequired#

Whether to track conversions for the short link.

Default: false

externalIdstringrequired#

tenantIdstringrequired#

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.

programIdstringrequired#

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

partnerIdstringrequired#

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

archivedbooleanrequired#

Whether the short link is archived.

Default: false

expiresAtstringrequired#

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

expiredUrlstringrequired#

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

disabledAtstringrequired#

The date and time when the short link was disabled. When a short link is disabled, it will redirect to its domain's not found URL, and its stats will be excluded from your overall stats.

passwordstringrequired#

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

proxybooleanrequired#

Whether the short link uses Custom Link Previews feature.

Default: false

titlestringrequired#

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

descriptionstringrequired#

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

imagestringrequired#

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

videostringrequired#

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewritebooleanrequired#

Whether the short link uses link cloaking.

Default: false

doIndexbooleanrequired#

Whether to allow search engines to index the short link.

Default: false

iosstringrequired#

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

androidstringrequired#

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

geoobjectrequired#

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

{key}string#

publicStatsbooleanrequired#

Whether the short link's stats are publicly accessible.

Default: false

tagsobject[]required#

The tags assigned to the short link.

Show child attributes

idstringrequired#

The unique ID of the tag.

namestringrequired#

The name of the tag.

colorenum<string>required#

The color of the tag.

Options:redyellowgreenbluepurplebrowngraypink

folderIdstringrequired#

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

commentsstringrequired#

The comments for the short link.

shortLinkstringrequired#

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

qrCodestringrequired#

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

utm_sourcestringrequired#

The UTM source of the short link.

utm_mediumstringrequired#

The UTM medium of the short link.

utm_campaignstringrequired#

The UTM campaign of the short link.

utm_termstringrequired#

The UTM term of the short link.

utm_contentstringrequired#

The UTM content of the short link.

testVariantsobject[]#

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

Items: 2–4

Show child attributes

urlstringrequired#

percentagenumberrequired#

Range: 10–90

testStartedAtstring#

The date and time when the tests started.

testCompletedAtstring#

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

userIdstringrequired#

The user ID of the creator of the short link.

workspaceIdstringrequired#

The workspace ID of the short link.

clicksnumberrequired#

The number of clicks on the short link.

Default: 0

leadsnumberrequired#

The number of leads the short link has generated.

Default: 0

conversionsnumberrequired#

The number of leads that converted to paying customers.

Default: 0

salesnumberrequired#

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

Default: 0

saleAmountnumberrequired#

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

Default: 0

lastClickedstringrequired#

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

createdAtstringrequired#

The date and time when the short link was created.

updatedAtstringrequired#

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

tagIdstringrequireddeprecated#

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

projectIdstringrequireddeprecated#

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

webhookIdsstring[]requireddeprecated#

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.

Deactivate partner Upsert partner link